firefeed-core 1.0.0__tar.gz

firefeed_core-1.0.0/LICENSE

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2025 FireFeed Project
+
+Данная лицензия разрешает лицам, получившим копию данного программного обеспечения 
+и сопутствующей документации (в дальнейшем «Программное обеспечение»), безвозмездно 
+использовать Программное обеспечение без ограничений, включая неограниченное право 
+на использование, копирование, изменение, слияние, публикацию, распространение, 
+сублицензирование и/или продажу копий Программного обеспечения, а также лицам, 
+которым предоставляется данное Программное обеспечение, при соблюдении следующих условий:
+
+Указанное выше уведомление об авторских правах и данные условия должны быть включены 
+во все копии или значимые части данного Программного обеспечения.
+
+ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, 
+ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ, 
+СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И ОТСУТСТВИЯ НАРУШЕНИЙ, НО НЕ ОГРАНИЧИВАЯСЬ 
+ИМИ. НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО 
+ИСКАМ, ЗА УЩЕРБ ИЛИ ПО ИНЫМ ТРЕБОВАНИЯМ, В ТОМ ЧИСЛЕ, ПРИ ДЕЙСТВИИ КОНТРАКТА, 
+ДЕЛИКТЕ ИЛИ ИНОЙ СИТУАЦИИ, ВОЗНИКШИМ ИЗ-ЗА ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ 
+ИЛИ ИНЫХ ДЕЙСТВИЙ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.
+
+---
+
+MIT License
+
+Copyright (c) 2024 FireFeed Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

firefeed_core-1.0.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: firefeed_core
+Version: 1.0.0
+Summary: Core utilities and models for FireFeed microservices
+Author-email: FireFeed <mail@firefeed.net>
+License: MIT
+Project-URL: Homepage, https://firefeed.net
+Project-URL: Repository, https://github.com/firefeed-net/firefeed-core
+Project-URL: Documentation, https://docs.firefeed.net
+Project-URL: Bug Tracker, https://github.com/firefeed-net/firefeed-core/issues
+Keywords: firefeed,microservices,core,rss,news
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: PyJWT>=2.8.0
+Requires-Dist: typing-extensions>=4.5.0
+Requires-Dist: datetime
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: aiosmtplib>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.11.0; extra == "test"
+Dynamic: license-file
+
+# FireFeed Core
+
+Core utilities and models for FireFeed microservices architecture.
+
+FireFeed Core is a shared library that provides common components for all FireFeed microservices, ensuring consistency, security, and reliability across the distributed system.
+
+## 🚀 Features
+
+- **API Client**: Robust HTTP client with authentication, retry policies, circuit breaker, and rate limiting
+- **JWT Authentication**: Service-to-service authentication with token management
+- **Exception Handling**: Comprehensive exception hierarchy for consistent error handling
+- **Configuration**: Pydantic-based configuration management
+- **Interfaces**: Abstract interfaces for service contracts
+- **Utilities**: Common utility functions and helpers
+
+## 📦 Installation
+
+```bash
+pip install firefeed-core
+```
+
+## 🔧 Quick Start
+
+### Basic API Client Usage
+
+```python
+import asyncio
+from firefeed_core import APIClient
+
+async def main():
+    # Initialize API client
+    async with APIClient(
+        base_url="http://firefeed-api:8000",
+        token="your-jwt-token",
+        service_id="firefeed-rss-parser"
+    ) as client:
+        
+        # Make authenticated requests
+        feeds = await client.get("/api/v1/internal/rss/feeds")
+        print(f"Found {len(feeds)} feeds")
+        
+        # Create new RSS item
+        new_item = await client.post("/api/v1/internal/rss/items", {
+            "title": "Test Article",
+            "content": "This is a test article",
+            "feed_id": 123
+        })
+
+asyncio.run(main())
+```
+
+### JWT Token Management
+
+```python
+from firefeed_core import ServiceTokenManager
+
+# Generate token for service
+token_manager = ServiceTokenManager(
+    secret_key="your-secret-key",
+    issuer="firefeed-api"
+)
+
+token = token_manager.generate_service_token(
+    service_id="firefeed-rss-parser",
+    audience="firefeed-api",
+    scopes=["rss:read", "rss:write"]
+)
+
+# Verify token
+payload = token_manager.verify_token(token)
+print(f"Token for service: {payload.sub}")
+```
+
+### Exception Handling
+
+```python
+from firefeed_core import APIException, NotFoundException
+
+try:
+    result = await client.get("/api/v1/internal/rss/feeds/999")
+except NotFoundException as e:
+    print(f"Feed not found: {e.message}")
+except APIException as e:
+    print(f"API error: {e.message}")
+```
+
+## 🔐 Authentication
+
+FireFeed Core uses JWT tokens for service-to-service authentication. Each service needs:
+
+1. **Service Token**: JWT token with appropriate scopes
+2. **Service ID**: Unique identifier for the service
+3. **Secret Key**: Shared secret for token verification
+
+### Environment Configuration
+
+Each service should have its own `.env` file:
+
+```bash
+# firefeed-rss-parser/.env
+FIREFEED_API_URL=http://firefeed-api:8000
+FIREFEED_API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+FIREFEED_RSS_PARSER_SERVICE_ID=rss-parser
+
+# firefeed-telegram-bot/.env
+FIREFEED_API_URL=http://firefeed-api:8000
+FIREFEED_API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+FIREFEED_TELEGRAM_BOT_SERVICE_ID=telegram-bot
+```
+
+### Token Scopes
+
+Services can be granted specific scopes for different operations:
+
+- `rss:read` - Read RSS data
+- `rss:write` - Create/modify RSS data
+- `users:read` - Read user data
+- `users:write` - Modify user data
+- `categories:read` - Read categories
+- `categories:write` - Modify categories
+
+## 🛠️ Advanced Features
+
+### Circuit Breaker
+
+Automatically prevents requests to failing services:
+
+```python
+from firefeed_core import APIClient
+
+client = APIClient(
+    base_url="http://service:8000",
+    token="token",
+    service_id="my-service",
+    circuit_breaker_failure_threshold=5,
+    circuit_breaker_timeout=60
+)
+```
+
+### Retry Policies
+
+Configurable retry with exponential backoff:
+
+```python
+client = APIClient(
+    base_url="http://service:8000",
+    token="token",
+    service_id="my-service",
+    max_retries=3
+)
+```
+
+### Rate Limiting
+
+Prevents API abuse:
+
+```python
+client = APIClient(
+    base_url="http://service:8000",
+    token="token",
+    service_id="my-service",
+    rate_limit_requests=100,
+    rate_limit_window=60
+)
+```
+
+## 📊 Monitoring
+
+Each API client provides comprehensive statistics:
+
+```python
+stats = client.get_stats()
+print(f"Circuit breaker state: {stats['circuit_breaker']['state']}")
+print(f"Rate limit usage: {stats['rate_limiter']['current_requests']}")
+```
+
+## 🏗️ Architecture
+
+FireFeed Core follows these principles:
+
+1. **API-First**: All services communicate via HTTP APIs only
+2. **Zero Direct Database Access**: Services never access databases directly
+3. **Token-Based Security**: All inter-service communication is authenticated
+4. **Fault Tolerance**: Circuit breakers, retries, and rate limiting
+5. **Consistent Error Handling**: Standardized exception hierarchy
+
+### Service Communication Flow
+
+```
+┌─────────────────────┐    JWT Token    ┌─────────────────────┐
+│  firefeed-rss-parser│ ──────────────→ │   firefeed-api      │
+│  (Dumb Service)     │                 │  (Smart Service)    │
+│                     │ ←────────────── │                     │
+│  - RSS Processing   │    HTTP API     │  - Database Access  │
+│  - No DB Access     │                 │  - Business Logic   │
+└─────────────────────┘                 └─────────────────────┘
+```
+
+## 🧪 Testing
+
+```bash
+# Install test dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=firefeed_core
+```
+
+## 📝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🔗 Related Projects
+
+- [FireFeed API](https://github.com/firefeed-net/firefeed-api) - Main API service
+- [FireFeed RSS Parser](https://github.com/firefeed-net/firefeed-rss-parser) - RSS processing service
+- [FireFeed Telegram Bot](https://github.com/firefeed-net/firefeed-telegram-bot) - Telegram bot service
+
+---
+
+**Note**: This is a core library intended for use within the FireFeed microservices ecosystem.

firefeed_core-1.0.0/README.md

@@ -0,0 +1,232 @@
+# FireFeed Core
+
+Core utilities and models for FireFeed microservices architecture.
+
+FireFeed Core is a shared library that provides common components for all FireFeed microservices, ensuring consistency, security, and reliability across the distributed system.
+
+## 🚀 Features
+
+- **API Client**: Robust HTTP client with authentication, retry policies, circuit breaker, and rate limiting
+- **JWT Authentication**: Service-to-service authentication with token management
+- **Exception Handling**: Comprehensive exception hierarchy for consistent error handling
+- **Configuration**: Pydantic-based configuration management
+- **Interfaces**: Abstract interfaces for service contracts
+- **Utilities**: Common utility functions and helpers
+
+## 📦 Installation
+
+```bash
+pip install firefeed-core
+```
+
+## 🔧 Quick Start
+
+### Basic API Client Usage
+
+```python
+import asyncio
+from firefeed_core import APIClient
+
+async def main():
+    # Initialize API client
+    async with APIClient(
+        base_url="http://firefeed-api:8000",
+        token="your-jwt-token",
+        service_id="firefeed-rss-parser"
+    ) as client:
+        
+        # Make authenticated requests
+        feeds = await client.get("/api/v1/internal/rss/feeds")
+        print(f"Found {len(feeds)} feeds")
+        
+        # Create new RSS item
+        new_item = await client.post("/api/v1/internal/rss/items", {
+            "title": "Test Article",
+            "content": "This is a test article",
+            "feed_id": 123
+        })
+
+asyncio.run(main())
+```
+
+### JWT Token Management
+
+```python
+from firefeed_core import ServiceTokenManager
+
+# Generate token for service
+token_manager = ServiceTokenManager(
+    secret_key="your-secret-key",
+    issuer="firefeed-api"
+)
+
+token = token_manager.generate_service_token(
+    service_id="firefeed-rss-parser",
+    audience="firefeed-api",
+    scopes=["rss:read", "rss:write"]
+)
+
+# Verify token
+payload = token_manager.verify_token(token)
+print(f"Token for service: {payload.sub}")
+```
+
+### Exception Handling
+
+```python
+from firefeed_core import APIException, NotFoundException
+
+try:
+    result = await client.get("/api/v1/internal/rss/feeds/999")
+except NotFoundException as e:
+    print(f"Feed not found: {e.message}")
+except APIException as e:
+    print(f"API error: {e.message}")
+```
+
+## 🔐 Authentication
+
+FireFeed Core uses JWT tokens for service-to-service authentication. Each service needs:
+
+1. **Service Token**: JWT token with appropriate scopes
+2. **Service ID**: Unique identifier for the service
+3. **Secret Key**: Shared secret for token verification
+
+### Environment Configuration
+
+Each service should have its own `.env` file:
+
+```bash
+# firefeed-rss-parser/.env
+FIREFEED_API_URL=http://firefeed-api:8000
+FIREFEED_API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+FIREFEED_RSS_PARSER_SERVICE_ID=rss-parser
+
+# firefeed-telegram-bot/.env
+FIREFEED_API_URL=http://firefeed-api:8000
+FIREFEED_API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+FIREFEED_TELEGRAM_BOT_SERVICE_ID=telegram-bot
+```
+
+### Token Scopes
+
+Services can be granted specific scopes for different operations:
+
+- `rss:read` - Read RSS data
+- `rss:write` - Create/modify RSS data
+- `users:read` - Read user data
+- `users:write` - Modify user data
+- `categories:read` - Read categories
+- `categories:write` - Modify categories
+
+## 🛠️ Advanced Features
+
+### Circuit Breaker
+
+Automatically prevents requests to failing services:
+
+```python
+from firefeed_core import APIClient
+
+client = APIClient(
+    base_url="http://service:8000",
+    token="token",
+    service_id="my-service",
+    circuit_breaker_failure_threshold=5,
+    circuit_breaker_timeout=60
+)
+```
+
+### Retry Policies
+
+Configurable retry with exponential backoff:
+
+```python
+client = APIClient(
+    base_url="http://service:8000",
+    token="token",
+    service_id="my-service",
+    max_retries=3
+)
+```
+
+### Rate Limiting
+
+Prevents API abuse:
+
+```python
+client = APIClient(
+    base_url="http://service:8000",
+    token="token",
+    service_id="my-service",
+    rate_limit_requests=100,
+    rate_limit_window=60
+)
+```
+
+## 📊 Monitoring
+
+Each API client provides comprehensive statistics:
+
+```python
+stats = client.get_stats()
+print(f"Circuit breaker state: {stats['circuit_breaker']['state']}")
+print(f"Rate limit usage: {stats['rate_limiter']['current_requests']}")
+```
+
+## 🏗️ Architecture
+
+FireFeed Core follows these principles:
+
+1. **API-First**: All services communicate via HTTP APIs only
+2. **Zero Direct Database Access**: Services never access databases directly
+3. **Token-Based Security**: All inter-service communication is authenticated
+4. **Fault Tolerance**: Circuit breakers, retries, and rate limiting
+5. **Consistent Error Handling**: Standardized exception hierarchy
+
+### Service Communication Flow
+
+```
+┌─────────────────────┐    JWT Token    ┌─────────────────────┐
+│  firefeed-rss-parser│ ──────────────→ │   firefeed-api      │
+│  (Dumb Service)     │                 │  (Smart Service)    │
+│                     │ ←────────────── │                     │
+│  - RSS Processing   │    HTTP API     │  - Database Access  │
+│  - No DB Access     │                 │  - Business Logic   │
+└─────────────────────┘                 └─────────────────────┘
+```
+
+## 🧪 Testing
+
+```bash
+# Install test dependencies
+pip install -e ".[test]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=firefeed_core
+```
+
+## 📝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🔗 Related Projects
+
+- [FireFeed API](https://github.com/firefeed-net/firefeed-api) - Main API service
+- [FireFeed RSS Parser](https://github.com/firefeed-net/firefeed-rss-parser) - RSS processing service
+- [FireFeed Telegram Bot](https://github.com/firefeed-net/firefeed-telegram-bot) - Telegram bot service
+
+---
+
+**Note**: This is a core library intended for use within the FireFeed microservices ecosystem.

firefeed_core-1.0.0/pyproject.toml

@@ -0,0 +1,139 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "firefeed_core"
+version = "1.0.0"
+description = "Core utilities and models for FireFeed microservices"
+authors = [
+    {name = "FireFeed", email = "mail@firefeed.net"}
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.13"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+keywords = ["firefeed", "microservices", "core", "rss", "news"]
+dependencies = [
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "httpx>=0.25.0",
+    "PyJWT>=2.8.0",
+    "typing-extensions>=4.5.0",
+    "datetime",
+    "jinja2>=3.1.0",
+    "aiosmtplib>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "mypy>=1.5.0",
+    "flake8>=6.0.0",
+    "pre-commit>=3.0.0",
+]
+
+test = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "pytest-mock>=3.11.0",
+]
+
+[project.urls]
+Homepage = "https://firefeed.net"
+Repository = "https://github.com/firefeed-net/firefeed-core"
+Documentation = "https://docs.firefeed.net"
+"Bug Tracker" = "https://github.com/firefeed-net/firefeed-core/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["firefeed_core*"]
+exclude = ["tests*"]
+
+[tool.black]
+line-length = 88
+target-version = ['py313']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+line_length = 88
+known_first_party = ["firefeed_core"]
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --strict-markers --cov=firefeed_core --cov-report=term-missing --cov-report=html"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "unit: marks tests as unit tests",
+]
+
+[tool.coverage.run]
+source = ["firefeed_core"]
+omit = [
+    "*/tests/*",
+    "*/test_*",
+    "*/conftest.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]

firefeed_core-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+