easyapi-django 0.35__tar.gz → 0.37__tar.gz

{easyapi_django-0.35/easyapi_django.egg-info → easyapi_django-0.37}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: easyapi_django
-Version: 0.35
+Version: 0.37
 Summary: A simple rest api generator for django based on models
 Author-email: Stamatios Stamou Jr <bushier.outsets.0c@icloud.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/ssjunior/easyapi-django
 Project-URL: Bug Tracker, https://github.com/ssjunior/easyapi-django/issues
 Classifier: Programming Language :: Python :: 3
@@ -75,7 +75,11 @@ MIDDLEWARE = [
     'easyapi.AuthMiddleware',        # session-based auth from Redis
     'easyapi.ExceptionMiddleware',
 ]
-TRUSTED_PROXIES = ['10.0.0.0/8']     # only trust X-Real-IP from these
+
+EASYAPI = {
+    'TRUSTED_PROXIES': ['10.0.0.0/8'],   # only trust X-Real-IP from these
+    # 'COOKIE_ID': 'sessionid', 'ENFORCE_TOKEN': True, ...
+}
 ```
 
 ## Create a resource
@@ -141,7 +145,7 @@ class YourResource(BaseResource):
 
     # Cache
     cache = True
-    cache_ttl = 600
+    cache_ttl = 600                    # default 120s; settings.CACHE_TTL overrides
 ```
 
 ## Querystrings
@@ -153,10 +157,118 @@ class YourResource(BaseResource):
 | `?field=value` / `?field__gte=...` | Filter on whitelisted fields                    |
 | `?fields=a,b`                      | Restrict returned fields (filtered by `list_fields`) |
 | `?filter=<json>`                   | Advanced filter expression on whitelisted fields |
-| `?segment_id=N`                    | Apply a stored segment                          |
+| `?<stored_filter_param>=N`         | Apply a server-side stored filter expression (see below) |
 | `?page=N&limit=M&order_by=field`   | Pagination + order                              |
 | `?normalize=true`                  | Return list as `{id: {...}}` instead of array   |
 
+## Saved filter expressions
+
+Layer-2 expressions can be persisted server-side and reapplied by id —
+saved views, marketing audiences, dashboard presets. The framework owns
+the URL plumbing; the project owns the storage, lookup and policy.
+
+Two pieces on the resource:
+
+```python
+class ClientResource(BaseResource):
+    model = Client
+    filter_fields = ['active', 'name']
+
+    stored_filter_param = 'segment_id'   # any name — view_id, audience_id, …
+
+    async def resolve_stored_filter(self, value):
+        seg = await Segment.objects.filter(
+            id=value, account=self.account_id   # tenant scoping etc.
+        ).afirst()
+        return seg.conditions if seg else None
+```
+
+When a request carries `?segment_id=42`, easyapi calls the hook, trusts
+its return value, and applies it through the same Layer-2 pipeline.
+Returning `None` raises `404`. The hook can raise `HTTPException(403,
+...)` itself for "exists but you can't access it."
+
+`?segment_id=` and `?filter=` compose with AND — saved view *plus*
+ad-hoc narrowing. The URL JSON still validates against `filter_fields`;
+the stored conditions skip that check because the hook owns them.
+
+For projects that let end users author stored expressions, validate at
+write time with the public helper:
+
+```python
+from easyapi import validate_conditions
+
+class SegmentResource(BaseResource):
+    model = Segment
+    create_fields = ['name', 'conditions', 'context_id']
+
+    async def hydrate(self, body):
+        conditions = body.get('conditions')
+        if conditions:
+            allowed = ALLOWED_FIELDS_BY_CONTEXT[body['context_id']]
+            validate_conditions(conditions, allowed)
+        return body
+```
+
+Server-side admin-only expressions can skip the write-time check; only
+user-authored ones need it.
+
+For projects with one `Segment` row type targeting many list resources,
+factor out a mixin so each resource opts in with two lines and the
+`filter_fields` whitelist auto-extends from a project registry:
+
+```python
+# modules/segment/mixin.py
+from django.db.models import Q
+from .constants import INCLUDE_FIELDS
+from .models import Segment, CONTEXT
+
+class SegmentMixin:
+    stored_filter_param = 'segment_id'
+    segment_context_id = None
+
+    def __init__(self):
+        super().__init__()
+        if self.segment_context_id is None:
+            return
+        label = CONTEXT.LABEL[self.segment_context_id]
+        bag = INCLUDE_FIELDS.get(label, {})
+        extra  = list(bag.get('segment_fields') or [])
+        extra += [m.split('__')[0] for m in bag.get('related_models') or []]
+        self.filter_fields = list(
+            dict.fromkeys((self.filter_fields or []) + extra)
+        )
+
+    async def resolve_stored_filter(self, value, **kwargs):
+        is_master = bool(self.user and (
+            self.user.get('is_admin') or self.user.get('is_owner')
+        ))
+        qs = Segment.objects.filter(
+            id=value, context_id=self.segment_context_id,
+        )
+        if not is_master:
+            qs = qs.filter(
+                Q(public=True) | Q(created_by_id=self.user['id'])
+            )
+        seg = await qs.afirst()
+        return seg.conditions if seg else None
+
+class AgentResource(SegmentMixin, BaseResource):
+    segment_context_id = CONTEXT.AGENT
+    model = Agent
+    filter_fields = ['agency_id']    # explicit URL shorthands
+    # The mixin unions in the segment_fields whitelist + related prefixes,
+    # so ?filter=<json> and segment authoring share one source of truth.
+```
+
+The minimum storage model is a JSON column:
+
+```python
+class Segment(models.Model):
+    name = models.CharField(max_length=120)
+    conditions = models.JSONField()
+```
+
 ## Pydantic schemas (optional)
 
 Set any of `create_schema`, `update_schema`, `list_schema` and easyapi
@@ -256,13 +368,45 @@ configuration needed; it just works for any project that uses
 `aset_tenant`. The auto-fold is keyed by `account_id is not None`, so an
 explicit `account_id = 0` still produces a per-tenant key (real value,
 not absence). Disable globally via
-`AUTO_SCOPE_CACHE_BY_ACCOUNT = False` if you have a single-tenant
-deployment and want the legacy key shape.
+`EASYAPI = {'AUTO_SCOPE_CACHE_BY_ACCOUNT': False}` if you have a
+single-tenant deployment and want the legacy key shape.
 
 If you override `_build_cache_key` in a project, call
 `self._account_cache_segment()` and append the result so the override
 inherits the tenant isolation.
 
+**TTL settings.** Two project-level knobs in the `EASYAPI` bag:
+
+- `CACHE_TTL` — default 120s; overrides the framework default for
+  resources that don't declare an explicit `cache_ttl`.
+- `CACHE_TTL_ENABLE` — default `True`; flip to `False` for a global
+  kill switch (every `cache=True` resource becomes `cache=False` at
+  runtime, no Redis read or write).
+
+Every easyapi setting lives inside the `EASYAPI = {...}` dict
+(DRF/Celery-style namespace):
+
+```python
+# settings.py
+EASYAPI = {
+    'CACHE_TTL': 300,
+    'CACHE_TTL_ENABLE': True,
+    'ENFORCE_TOKEN': True,
+    'COOKIE_ID': 'sessionid',
+    'RATE_LIMITS': {...},
+}
+```
+
+Inside the bag the historical `EASYAPI_` prefix is redundant —
+`EASYAPI_API_KEY_RESOLVER` and `API_KEY_RESOLVER` resolve to the
+same setting.
+
+`CACHE_TTL` only sets the default — resources that declare
+`cache_ttl = N` keep that explicit value.
+`CACHE_TTL_ENABLE = False` is a kill switch that forces
+`self.cache = False` for every request, useful for incident response
+without code edits.
+
 **Per-scope caching.** When the response varies on a user/account
 dimension *inside* the same tenant — role, space, plan, country —
 declare it with `cache_scope_fields` so users sharing the same scope
@@ -324,7 +468,7 @@ middleware in effect.
 
 - Session cookie validated against `^[a-zA-Z0-9_\-:]{5,100}$`.
 - `?fields=` is filtered against `list_fields` to prevent attribute leakage.
-- `?filter=` and `segment_id` are validated against `filter_fields`.
+- `?filter=` is validated against `filter_fields`. Stored filter expressions are validated by the project (typically at write time via `validate_conditions`).
 - `owner_field` scopes PATCH/DELETE to rows owned by the authenticated user.
 - Request rate limiting runs inside `BaseResource.dispatch`; edge scanner
   blocking runs in `SecurityMiddleware` before the view.
@@ -482,11 +626,13 @@ pip install -r requirements-dev.txt
 pytest
 ```
 
-216 tests covering util, redis, cache, filters, filter validation, init,
-auth tokens (incl. nonce replay), schemas, openapi, helpers, serializer,
-client_ip, SecurityMiddleware, dispatch error handling, tenant connection
-and registry, MCP middleware chain, route gating, WS subscription
-hardening, public exports, and WebSocket optional import.
+301 tests covering util, redis, cache (incl. per-account auto-fold and
+per-scope keys), filters, filter validation, init, auth tokens (incl.
+nonce replay), schemas, openapi, helpers, serializer (incl. per-call
+timezone subclass), client_ip, allowed-domain checks, SecurityMiddleware,
+dispatch error handling, tenant connection and registry, MCP middleware
+chain, route gating, WS subscription hardening, public exports, and
+WebSocket optional import.
 
 ## Author
 

{easyapi_django-0.35 → easyapi_django-0.37}/README.md

@@ -48,7 +48,11 @@ MIDDLEWARE = [
     'easyapi.AuthMiddleware',        # session-based auth from Redis
     'easyapi.ExceptionMiddleware',
 ]
-TRUSTED_PROXIES = ['10.0.0.0/8']     # only trust X-Real-IP from these
+
+EASYAPI = {
+    'TRUSTED_PROXIES': ['10.0.0.0/8'],   # only trust X-Real-IP from these
+    # 'COOKIE_ID': 'sessionid', 'ENFORCE_TOKEN': True, ...
+}
 ```
 
 ## Create a resource
@@ -114,7 +118,7 @@ class YourResource(BaseResource):
 
     # Cache
     cache = True
-    cache_ttl = 600
+    cache_ttl = 600                    # default 120s; settings.CACHE_TTL overrides
 ```
 
 ## Querystrings
@@ -126,10 +130,118 @@ class YourResource(BaseResource):
 | `?field=value` / `?field__gte=...` | Filter on whitelisted fields                    |
 | `?fields=a,b`                      | Restrict returned fields (filtered by `list_fields`) |
 | `?filter=<json>`                   | Advanced filter expression on whitelisted fields |
-| `?segment_id=N`                    | Apply a stored segment                          |
+| `?<stored_filter_param>=N`         | Apply a server-side stored filter expression (see below) |
 | `?page=N&limit=M&order_by=field`   | Pagination + order                              |
 | `?normalize=true`                  | Return list as `{id: {...}}` instead of array   |
 
+## Saved filter expressions
+
+Layer-2 expressions can be persisted server-side and reapplied by id —
+saved views, marketing audiences, dashboard presets. The framework owns
+the URL plumbing; the project owns the storage, lookup and policy.
+
+Two pieces on the resource:
+
+```python
+class ClientResource(BaseResource):
+    model = Client
+    filter_fields = ['active', 'name']
+
+    stored_filter_param = 'segment_id'   # any name — view_id, audience_id, …
+
+    async def resolve_stored_filter(self, value):
+        seg = await Segment.objects.filter(
+            id=value, account=self.account_id   # tenant scoping etc.
+        ).afirst()
+        return seg.conditions if seg else None
+```
+
+When a request carries `?segment_id=42`, easyapi calls the hook, trusts
+its return value, and applies it through the same Layer-2 pipeline.
+Returning `None` raises `404`. The hook can raise `HTTPException(403,
+...)` itself for "exists but you can't access it."
+
+`?segment_id=` and `?filter=` compose with AND — saved view *plus*
+ad-hoc narrowing. The URL JSON still validates against `filter_fields`;
+the stored conditions skip that check because the hook owns them.
+
+For projects that let end users author stored expressions, validate at
+write time with the public helper:
+
+```python
+from easyapi import validate_conditions
+
+class SegmentResource(BaseResource):
+    model = Segment
+    create_fields = ['name', 'conditions', 'context_id']
+
+    async def hydrate(self, body):
+        conditions = body.get('conditions')
+        if conditions:
+            allowed = ALLOWED_FIELDS_BY_CONTEXT[body['context_id']]
+            validate_conditions(conditions, allowed)
+        return body
+```
+
+Server-side admin-only expressions can skip the write-time check; only
+user-authored ones need it.
+
+For projects with one `Segment` row type targeting many list resources,
+factor out a mixin so each resource opts in with two lines and the
+`filter_fields` whitelist auto-extends from a project registry:
+
+```python
+# modules/segment/mixin.py
+from django.db.models import Q
+from .constants import INCLUDE_FIELDS
+from .models import Segment, CONTEXT
+
+class SegmentMixin:
+    stored_filter_param = 'segment_id'
+    segment_context_id = None
+
+    def __init__(self):
+        super().__init__()
+        if self.segment_context_id is None:
+            return
+        label = CONTEXT.LABEL[self.segment_context_id]
+        bag = INCLUDE_FIELDS.get(label, {})
+        extra  = list(bag.get('segment_fields') or [])
+        extra += [m.split('__')[0] for m in bag.get('related_models') or []]
+        self.filter_fields = list(
+            dict.fromkeys((self.filter_fields or []) + extra)
+        )
+
+    async def resolve_stored_filter(self, value, **kwargs):
+        is_master = bool(self.user and (
+            self.user.get('is_admin') or self.user.get('is_owner')
+        ))
+        qs = Segment.objects.filter(
+            id=value, context_id=self.segment_context_id,
+        )
+        if not is_master:
+            qs = qs.filter(
+                Q(public=True) | Q(created_by_id=self.user['id'])
+            )
+        seg = await qs.afirst()
+        return seg.conditions if seg else None
+
+class AgentResource(SegmentMixin, BaseResource):
+    segment_context_id = CONTEXT.AGENT
+    model = Agent
+    filter_fields = ['agency_id']    # explicit URL shorthands
+    # The mixin unions in the segment_fields whitelist + related prefixes,
+    # so ?filter=<json> and segment authoring share one source of truth.
+```
+
+The minimum storage model is a JSON column:
+
+```python
+class Segment(models.Model):
+    name = models.CharField(max_length=120)
+    conditions = models.JSONField()
+```
+
 ## Pydantic schemas (optional)
 
 Set any of `create_schema`, `update_schema`, `list_schema` and easyapi
@@ -229,13 +341,45 @@ configuration needed; it just works for any project that uses
 `aset_tenant`. The auto-fold is keyed by `account_id is not None`, so an
 explicit `account_id = 0` still produces a per-tenant key (real value,
 not absence). Disable globally via
-`AUTO_SCOPE_CACHE_BY_ACCOUNT = False` if you have a single-tenant
-deployment and want the legacy key shape.
+`EASYAPI = {'AUTO_SCOPE_CACHE_BY_ACCOUNT': False}` if you have a
+single-tenant deployment and want the legacy key shape.
 
 If you override `_build_cache_key` in a project, call
 `self._account_cache_segment()` and append the result so the override
 inherits the tenant isolation.
 
+**TTL settings.** Two project-level knobs in the `EASYAPI` bag:
+
+- `CACHE_TTL` — default 120s; overrides the framework default for
+  resources that don't declare an explicit `cache_ttl`.
+- `CACHE_TTL_ENABLE` — default `True`; flip to `False` for a global
+  kill switch (every `cache=True` resource becomes `cache=False` at
+  runtime, no Redis read or write).
+
+Every easyapi setting lives inside the `EASYAPI = {...}` dict
+(DRF/Celery-style namespace):
+
+```python
+# settings.py
+EASYAPI = {
+    'CACHE_TTL': 300,
+    'CACHE_TTL_ENABLE': True,
+    'ENFORCE_TOKEN': True,
+    'COOKIE_ID': 'sessionid',
+    'RATE_LIMITS': {...},
+}
+```
+
+Inside the bag the historical `EASYAPI_` prefix is redundant —
+`EASYAPI_API_KEY_RESOLVER` and `API_KEY_RESOLVER` resolve to the
+same setting.
+
+`CACHE_TTL` only sets the default — resources that declare
+`cache_ttl = N` keep that explicit value.
+`CACHE_TTL_ENABLE = False` is a kill switch that forces
+`self.cache = False` for every request, useful for incident response
+without code edits.
+
 **Per-scope caching.** When the response varies on a user/account
 dimension *inside* the same tenant — role, space, plan, country —
 declare it with `cache_scope_fields` so users sharing the same scope
@@ -297,7 +441,7 @@ middleware in effect.
 
 - Session cookie validated against `^[a-zA-Z0-9_\-:]{5,100}$`.
 - `?fields=` is filtered against `list_fields` to prevent attribute leakage.
-- `?filter=` and `segment_id` are validated against `filter_fields`.
+- `?filter=` is validated against `filter_fields`. Stored filter expressions are validated by the project (typically at write time via `validate_conditions`).
 - `owner_field` scopes PATCH/DELETE to rows owned by the authenticated user.
 - Request rate limiting runs inside `BaseResource.dispatch`; edge scanner
   blocking runs in `SecurityMiddleware` before the view.
@@ -455,11 +599,13 @@ pip install -r requirements-dev.txt
 pytest
 ```
 
-216 tests covering util, redis, cache, filters, filter validation, init,
-auth tokens (incl. nonce replay), schemas, openapi, helpers, serializer,
-client_ip, SecurityMiddleware, dispatch error handling, tenant connection
-and registry, MCP middleware chain, route gating, WS subscription
-hardening, public exports, and WebSocket optional import.
+301 tests covering util, redis, cache (incl. per-account auto-fold and
+per-scope keys), filters, filter validation, init, auth tokens (incl.
+nonce replay), schemas, openapi, helpers, serializer (incl. per-call
+timezone subclass), client_ip, allowed-domain checks, SecurityMiddleware,
+dispatch error handling, tenant connection and registry, MCP middleware
+chain, route gating, WS subscription hardening, public exports, and
+WebSocket optional import.
 
 ## Author
 

{easyapi_django-0.35 → easyapi_django-0.37}/easyapi/__init__.py

@@ -8,7 +8,7 @@ from easyapi.tenant.db_router import DBRouter  # noqa
 from easyapi.tenant.tenant import aset_tenant, db_state, get_account, get_master_user, get_tenant, set_tenant  # noqa
 # set_default / unset_default are SCRIPT-ONLY (mutate global default DB);
 # import them directly from easyapi.tenant.tenant when really needed.
-from easyapi.filters import Filter as OrmFilter  # noqa
+from easyapi.filters import Filter as OrmFilter, validate_conditions  # noqa
 from easyapi.redis_config import get_cache_stats, reset_cache_stats  # noqa: F401
 from easyapi.schemas import openapi  # noqa: F401
 from easyapi.openapi import build_spec  # noqa: F401

{easyapi_django-0.35 → easyapi_django-0.37}/easyapi/auth.py

@@ -5,10 +5,17 @@ from time import time
 
 from .exception import HTTPException
 from .redis_config import KEY_PREFIX, get_redis
+from .settings_helper import get_token_max_drift_ms
 
 _NONCE_RE = re.compile(r'^[A-Za-z0-9_\-]{1,64}$')
 
 
+def _resolve_max_drift_ms(max_drift_ms):
+    if max_drift_ms is None:
+        return get_token_max_drift_ms()
+    return max_drift_ms
+
+
 def make_token(session_token, nonce, timestamp_ms=None):
     """Build an X-Token value from the session token, a nonce and a
     timestamp. Format: ``<timestamp_ms>.<nonce>.<hex_hmac>``.
@@ -25,7 +32,7 @@ def make_token(session_token, nonce, timestamp_ms=None):
     return f'{timestamp_ms}.{nonce}.{digest}'
 
 
-def validate_token(token, session_token, max_drift_ms=5000):
+def validate_token(token, session_token, max_drift_ms=None):
     """Validate the X-Token anti-replay header.
 
     Token format: ``<timestamp_ms>.<nonce>.<hex_hmac>``.
@@ -33,6 +40,8 @@ def validate_token(token, session_token, max_drift_ms=5000):
 
     Raises HTTPException(403) on any failure.
     """
+    max_drift_ms = _resolve_max_drift_ms(max_drift_ms)
+
     if not token:
         raise HTTPException(403, 'Not allowed, missing token')
     if not session_token:
@@ -61,12 +70,14 @@ def validate_token(token, session_token, max_drift_ms=5000):
     return nonce, timestamp_ms
 
 
-async def consume_nonce(session_token, nonce, timestamp_ms, max_drift_ms=5000):
+async def consume_nonce(session_token, nonce, timestamp_ms, max_drift_ms=None):
     """Reserve nonce in Redis to prevent replay within the drift window.
 
     Keyed by sha256(session_token):nonce. TTL = 2 * max_drift_ms (ms).
     Raises HTTPException(403) if nonce was already used.
     """
+    max_drift_ms = _resolve_max_drift_ms(max_drift_ms)
+
     redis = get_redis()
     sess_hash = hashlib.sha256(session_token.encode('utf-8')).hexdigest()[:16]
     key = f'{KEY_PREFIX}nonce:{sess_hash}:{nonce}'
@@ -76,7 +87,8 @@ async def consume_nonce(session_token, nonce, timestamp_ms, max_drift_ms=5000):
         raise HTTPException(403, 'Not allowed, replayed token')
 
 
-async def validate_token_async(token, session_token, max_drift_ms=5000):
+async def validate_token_async(token, session_token, max_drift_ms=None):
     """Validate X-Token and consume nonce atomically (Redis SETNX)."""
+    max_drift_ms = _resolve_max_drift_ms(max_drift_ms)
     nonce, timestamp_ms = validate_token(token, session_token, max_drift_ms)
     await consume_nonce(session_token, nonce, timestamp_ms, max_drift_ms)