Quota Enforcement — Flow Diagram

Audience: scanner operators and engineers who need to understand how free-tier quota limits are enforced at request time.

This guide traces the request path through the quota gate: the key parameters, the Valkey key layout, the enforcement algorithm, and the metrics you can alert on. For the user-facing quota model and how to obtain a free token, see the Free-Tier Quota overview. For policy rationale and legal aspects, see the Quota Legal FAQ.

0 · Key parameters

Symbol	Value	Meaning
`L_anon`	{{quota_anon}}	Daily ceiling for anonymous users
`L_jwt`	{{quota_token}}	Daily ceiling for token holders
`T_warn`	`200`	Soft reminder threshold
`D_soft`	`5 000 ms`	Delay applied to the first 30 over-quota scans
`D_hard`	`60 000 ms`	Delay applied to all scans beyond the soft window

L_active is L_jwt when a valid token is present; otherwise it is L_anon.

1 · Sequence diagram

sequenceDiagram
    participant C as Client
    participant API as Scanner API
    participant VALKEY as Valkey (quota)
    C->>API: /scan
    API->>VALKEY: INCR quota:
    VALKEY-->>API: new_count
    alt new_count ≤ L_active
        API-->>C: 202 Accepted (no delay)
    else new_count ≤ L_active + 30
        API->>C: wait D_soft
        API-->>C: 202 Accepted
    else
        API->>C: wait D_hard
        API-->>C: 202 Accepted
    end

Counters auto-expire 24 h after the first increment (00:00 UTC reset).

2 · Valkey key layout

Key pattern	TTL	Description
`quota:ip:<sha256>`	24 h	Anonymous quota per hashed IP
`quota:tid:<sha256>`	24 h	Token quota per hashed token-ID
`quota:ip:<sha256>:ts`	24 h	First-seen timestamp (ISO 8601)

Keys share a common TTL for efficient mass expiry via valkey-cli --scan.

3 · Pseudocode (Go-style)

func gate(key string, limit int) (delay time.Duration) {
    cnt, _ := rdb.Incr(ctx, key).Result()

    switch {
    case cnt <= limit:
        return 0 // under quota
    case cnt <= limit+30:
        return 5 * time.Second
    default:
        return 60 * time.Second
    }
}

The middleware applies time.Sleep(delay) before processing the scan request; it never returns HTTP 429 under the free tier.

4 · Metrics & monitoring

Metric	PromQL sample	Alert on
`stella_quota_soft_hits_total`	`increase(...[5m]) > 50`	Many users near the limit
`stella_quota_hard_hits_total`	`rate(...[1h]) > 0.1`	Potential abuse
Average delay per request	`histogram_quantile(0.95, sum(rate(...)))`	P95 < 1 s expected

Free-Tier Quota overview — the user-facing quota model.
Quota Legal FAQ — rationale and legal context.