angee.base.ingress

Pre-elevation checks for curated anonymous HTTP ingress.

Anonymous writes are deliberately outside the normal authenticated GraphQL surface. Every such endpoint must pass this utility before entering system_context: it bounds the raw body, spends a per-IP rate-limit token, parses a JSON object, rejects undeclared envelope fields, checks a honeypot, and optionally delegates capability-token validation to the endpoint owner.

AnonymousIngressRejected

class AnonymousIngressRejected(Exception)

A stable client-facing rejection raised before any actor elevation.

AnonymousIngressTooLarge

class AnonymousIngressTooLarge(AnonymousIngressRejected)

The request body exceeds the endpoint's byte cap.

AnonymousIngressUnsupportedMedia

class AnonymousIngressUnsupportedMedia(AnonymousIngressRejected)

The endpoint accepts only JSON request bodies.

AnonymousIngressRateLimited

class AnonymousIngressRateLimited(AnonymousIngressRejected)

The source IP exhausted this endpoint's fixed-window burst.

AnonymousIngressTokenRejected

class AnonymousIngressTokenRejected(AnonymousIngressRejected)

The optional endpoint-owned capability-token hook denied the request.

AnonymousIngressUnavailable

class AnonymousIngressUnavailable(AnonymousIngressRejected)

A required guard dependency failed, so ingress fails closed.

AnonymousIngressRateLimit

@dataclass(frozen=True)
class AnonymousIngressRateLimit()

One fixed-window rate-limit bucket shared by an endpoint scope.

AnonymousIngressPolicy

@dataclass(frozen=True)
class AnonymousIngressPolicy()

The reusable checks one curated JSON endpoint opts into.

AnonymousIngress

@dataclass(frozen=True)
class AnonymousIngress()

A checked JSON envelope safe for an endpoint to interpret.

guard_anonymous_ingress

def guard_anonymous_ingress(
        request: HttpRequest,
        policy: AnonymousIngressPolicy) -> AnonymousIngress

Run every anonymous-ingress check and return the parsed JSON envelope.

The caller must invoke this before any system_context. REMOTE_ADDR is the source identity: forwarding headers are client-controlled unless a deployment's trusted proxy has already rewritten the WSGI/ASGI peer address. Cache failure rejects with 503 rather than silently disabling rate limiting. A filled honeypot is returned as dropped=True so the endpoint can emit its normal success-shaped response without performing a write.