Feat: rate limiting

[primetheus]

Release v0.2.5: Rate Limiting and Enhanced OAuth2 Configuration

This release improves on v0.2.0's OAuth2 and httpx features and adds rate limiting, environment variable support for OAuth2, and reorganizing samples for a better developer experience.

New Features

Rate Limiting

• Automatic Retry Logic: Exponential back-off with configurable parameters
• GitHub API Compliance: Respects Retry-After headers and rate limit guidance
• Decorator Support: @with_rate_limit_handling for seamless integration
• Manual Control: retry_with_rate_limit method for selective rate limiting
• Monitoring Endpoints: Rate limit status and error tracking
• Configurable Parameters: rate_limit_retries and rate_limit_max_sleep options

Enhanced OAuth2 Configuration

• Environment Variable Support: All OAuth2 settings now configurable via environment variables
• New Environment Variables:
  • GITHUBAPP_OAUTH_CLIENT_ID
  • GITHUBAPP_OAUTH_CLIENT_SECRET
  • GITHUBAPP_OAUTH_SESSION_SECRET
  • GITHUBAPP_OAUTH_REDIRECT_URI
  • GITHUBAPP_OAUTH_SCOPES
  • GITHUBAPP_ENABLE_OAUTH
  • GITHUBAPP_OAUTH_ROUTES_PREFIX
• Flexible Configuration: Use environment variables, constructor parameters, or mix both approaches
• Improved Session Management: Enhanced JWT session handling with environment configuration

Sample Applications Restructure

• Learning Progression: Restructured samples into numbered sequence (01-04)
• 01-basic-webhook: Basic GitHub App functionality
• 02-configuration: Environment vs constructor configuration patterns
• 03-oauth2-integration: OAuth2 authentication examples with both configuration methods
• 04-advanced-features: Rate limiting and production patterns
• Sample Consistency: All examples use the same cruel-closer to focus on functional scope
• Environment Files: .env.example files for each sample with proper OAuth2 configuration

Technical Improvements

• Enhanced Core Library: Extended GitHubApp class with rate limiting
• OAuth2 Environment Loading: Added OAuth2 environment variable loading in load_env()
• Test Coverage: New test suite for rate limiting functionality
• Documentation: Updated README with detailed rate limiting and OAuth2 environment configuration
• Configuration Flexibility: Support for both constructor parameters and environment variables

Cleanup

• Removed the original cruel_closer sample in favor of more specific functional samples
• Consolidated sample structure for better developer experience
• Added sample-specific README files with usage examples

Breaking Changes

• Rate Limiting: New constructor parameters for rate limiting configuration
• Sample Structure: Deprecated cruel_closer sample removed (use 01-basic-webhook instead)
• OAuth2 Routes: Continue to require oauth_session_secret parameter (from v0.2.0)

Testing

• All existing tests continue to pass
• New test suite for rate limiting functionality (tests/test_rate_limiting.py)
• Enhanced OAuth2 test coverage
• Maintained backward compatibility for core webhook functionality

Documentation

• Added rate limiting configuration guide to README
• OAuth2 environment variable documentation
• Sample-specific README files with usage examples
• Environment variable configuration examples
• Implementation phase documentation in .github/prompts/

---

Version: 0.2.5
Branch: primetheus/rate-limiting
Base: v0.2.0 (OAuth2 and httpx migration)
Compatibility: Python 3.8+, FastAPI 0.68+

This release focuses on production readiness with automatic rate limiting and improved developer experience through environment variable support and better sample organization.

[Copilot]

Pull Request Overview

This release introduces rate limiting and enhanced OAuth2 configuration capabilities to the FastAPI-GitHubApp library. The PR adds automatic rate limit handling with exponential backoff for GitHub API calls, environment variable support for OAuth2 configuration, and reorganizes sample applications into a structured learning progression.

• Comprehensive rate limiting with @with_rate_limit_handling decorator and manual retry functionality
• OAuth2 environment variable configuration alongside existing constructor parameters
• Restructured samples into numbered sequence (01-04) demonstrating progressive complexity

Reviewed Changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/githubapp/core.py	Adds rate limiting classes, decorator, and enhanced OAuth2 environment loading
src/githubapp/init.py	Exports new rate limiting decorator
src/githubapp/session.py	Formats session token creation method parameters
src/githubapp/oauth.py	Formats OAuth2 method signatures and conditional expressions
tests/test_rate_limiting.py	New comprehensive test suite for rate limiting functionality
tests/test_oauth*.py	Formatting improvements for OAuth2 test files
tests/test_core.py	Minor formatting addition
samples/*	New structured sample applications demonstrating features
pyproject.toml	Version bump to 0.2.5
README.md	Updated documentation with rate limiting and OAuth2 details
CHANGELOG.md	New changelog format with detailed release notes

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}