edge

type Hold struct {
	// Action is the enforced action: challenge, restrict or block.
	Action string
	// Reason is the scorer's short cause, carried for the audit record.
	Reason string
	// Decision is the scorer's decision id, so a held enforcement is traceable
	// back to the judgement that produced it.
	Decision string
	// Until is when the hold lapses and the scorer is asked again.
	Until time.Time
}

type Pattern struct {
	// Requests is how many requests this caller made in the window.
	Requests int
	// Failures is how many of them ended 401 or 403.
	Failures int
	// Paths is the approximate number of distinct paths it touched, saturating at 64.
	Paths int
	// Peers is the approximate number of distinct credentials this client IP
	// presented in the window, saturating at 64 — the stuffing signature.
	Peers int
	// Lane is the lane this request was classed into, derived from Class and the
	// counts above by Lane. It is an OUTPUT: the caller does not state it and the
	// gate does not compute it a second time.
	Lane string
	// Strain is what the scope's ceiling did to THIS observation: "" when the
	// caller was measured, StrainRefuse when the ceiling was full of live callers
	// and this one could not be admitted — so every count above is zero because
	// nothing was measured. A gate reads it to avoid treating an unmeasured caller
	// as a caller making its first request.
	Strain string
	// Rise names a strain grade the FIRST time this scope reaches it, and is ""
	// on every other observation. It exists so a degraded sensor produces one log
	// line per grade change instead of one per request, without this package
	// holding a logger.
	Rise string
}

type Policy struct {
	// CORSOrigins is the PLATFORM-scope CORS allowlist EdgeCORS admits: an exact
	// origin, a bare host, or a "*.host" wildcard. Writable only by a SuperAdmin —
	// CORS is evaluated before identity, so it has no tenant to scope to.
	CORSOrigins []string `json:"cors_origins,omitempty"`
	// PerIPRPM is the PLATFORM-scope pre-auth flood cap: requests EdgeRateLimit
	// admits per WindowSec from one client IP. SuperAdmin-only, same reason.
	PerIPRPM int `json:"per_ip_rpm,omitempty"`
	// WindowSec is the window PerIPRPM is counted over, in seconds. SuperAdmin-only.
	WindowSec int `json:"window_sec,omitempty"`

	// OrgRPM is the org's OWN authenticated rate ceiling, requests per minute, as
	// ScopeRateLimit enforces it. Unset inherits the platform default, then the
	// static boot default.
	OrgRPM int `json:"org_rpm,omitempty"`
	// CacheTTLSec is the org's default edge-cache TTL for its responses, in seconds;
	// 0 means no caching. Unset inherits the platform default.
	CacheTTLSec int `json:"cache_ttl_sec,omitempty"`
	// CachePaths overrides CacheTTLSec per path PREFIX (key "/v1/models" → seconds).
	// The longest matching prefix wins.
	CachePaths map[string]int `json:"cache_paths,omitempty"`
	// Methods is the allowlist of HTTP methods the edge accepts for this org. Empty
	// means all are accepted.
	Methods []string `json:"methods,omitempty"`
	// Mode is the abuse gate's posture for THIS scope: "shadow" scores traffic and
	// records the verdict without acting on it, "live" enforces it. Unset means
	// shadow.
	//
	// It is the one per-org field that does NOT inherit. Every other field here
	// layers a platform default under the org's own value, which is right for a
	// default: a tenant that sets no rate ceiling should get the platform's. Mode
	// is not a default, it is an ARMING DECISION — it is what makes a statistical
	// judgement start refusing real traffic — and inheriting it means arming one
	// scope arms every tenant that never asked for it, without a write to their
	// row and without anything in their config changing. So a tenant is live only
	// if that tenant's OWN row says live, and the platform row's mode governs
	// exactly one scope: the anonymous lane, which has no tenant of its own.
	//
	// It is also not self-service. Writing it requires SuperAdmin (see the
	// /v1/gateway config op): the subject of an abuse control does not get to
	// switch the control off.
	Mode string `json:"mode,omitempty"`

	// UpdatedAt is the unix second this policy row was last written. Server-stamped;
	// a client-supplied value is ignored.
	UpdatedAt int64 `json:"updated_at,omitempty"`
	// UpdatedBy is the validated user id that wrote this policy row. Server-stamped;
	// a client-supplied value is ignored.
	UpdatedBy string `json:"updated_by,omitempty"`
}

type Signal struct {
	// Org is the VERIFIED tenant; "" for a caller with no tenant — the anonymous
	// lane, which is one scope for the whole internet.
	Org string
	// Cred is the fingerprint of a credential the identity boundary VALIDATED,
	// and "" when it validated none. It is the ONLY thing that can key a caller,
	// because it is the only credential fact the caller does not choose: we minted
	// it, to a named principal, and we can revoke it. A request whose credential
	// did not validate has no identity beyond where it came from, and is keyed on
	// its address.
	Cred string
	// Presented is the fingerprint of whatever credential the request carried,
	// valid or not. It is counted only as SPREAD — how many distinct credentials
	// one address tried, which is the stuffing signature — and is never a key: a
	// value the caller picks per request cannot be an identity.
	Presented string
	// IP is the client address, resolved by cloud.ClientIP from the socket peer
	// and our own forwarding hops. It is the anonymous caller's only identity.
	IP string
	// Path is the request path, hashed into the spread word (never stored).
	Path string
	// Class is the credential class the identity boundary's answer implies:
	// session, secret, publishable or anonymous. It selects the lane together with
	// the pattern; it is not itself a lane.
	Class string
}

type Store struct {
	// contains filtered or unexported fields
}

type Traffic struct {
	// contains filtered or unexported fields
}

type TrafficCaller struct {
	// Cred is the caller's key: a credential fingerprint (a per-process one-way
	// digest, not a key) for a validated caller, and "ip:<addr>" for one that
	// presented no credential we could validate.
	Cred string `json:"cred"`
	// Requests is its request count in the window.
	Requests int `json:"requests"`
	// Failures is how many ended 401 or 403.
	Failures int `json:"failures"`
	// Paths is the approximate number of distinct paths it touched (max 64).
	Paths int `json:"paths"`
	// Action is the verdict currently held against it, if any.
	Action string `json:"action,omitempty"`
	// Reason is why that verdict was reached.
	Reason string `json:"reason,omitempty"`
	// HeldUntil is when the held verdict lapses, unix seconds.
	HeldUntil int64 `json:"held_until,omitempty"`
}

type TrafficView struct {
	// Org is the scope this view was taken for — the validated principal's own,
	// never a value the caller supplied. Empty names the anonymous lane, the one
	// scope that has no tenant.
	Org string `json:"org"`
	// WindowSec is the span the counts cover, in seconds.
	WindowSec int `json:"window_sec"`
	// Mode is the abuse gate's posture for this scope: "shadow" records the scorer's
	// action without enforcing it, "live" enforces it.
	Mode string `json:"mode"`
	// Requests is how many requests this scope made in the window.
	Requests int `json:"requests"`
	// Denied is how many of them the gate refused.
	Denied int `json:"denied"`
	// Screens is how many of them were put to the scorer — the billable unit of
	// the risk product. Counted from the first request, whatever the SKU costs.
	Screens int `json:"screens"`
	// Unscored is how many of those screens got NO answer — the scorer was absent,
	// stuck, slow, erroring or silent. An unanswered screen allows ordinary
	// traffic, so this is the number that separates "a quiet day" from "the judge
	// stopped answering and nothing said so".
	Unscored int `json:"unscored,omitempty"`
	// Strain is what this scope's ceilings are doing: "clear" below them, "full"
	// at them, "refuse" once a caller has been turned away inside this window —
	// which means that caller is UNMEASURED and the numbers here are a sample
	// rather than a census. It is reported rather than logged because the
	// alternative — a bound that degrades a scope silently — is the failure this
	// design exists to rule out. No other scope can move it.
	Strain string `json:"strain"`
	// Tracked is how many callers this scope holds state for right now, and
	// Ceiling is the most it may hold. Tracked == Ceiling is the fact a bound
	// that binds cannot hide.
	Tracked int `json:"tracked"`
	// Ceiling is the most callers this scope may hold at once.
	Ceiling int `json:"ceiling"`
	// Refused is how many callers this scope's ceilings turned away in the window.
	Refused int `json:"refused,omitempty"`
	// Blind is how many requests in the window carried no identity to attribute
	// them to — no validated credential and no client address. Non-zero on a
	// public plane means the client address is not reaching this process (a TCP
	// load balancer with no PROXY protocol in front of it, typically), so this
	// scope's callers cannot be told apart and nothing can be held against them.
	Blind int `json:"blind,omitempty"`
	// Lanes is the request count per lane — agent, human, bot, unknown. This is
	// the split that separates a customer's automation from a scraper.
	Lanes map[string]int `json:"lanes"`
	// Callers is the scope's busiest callers this window. A credentialed caller
	// appears as a FINGERPRINT — a per-process one-way digest: enough to recognise
	// the same caller across requests, never enough to reconstruct the credential.
	Callers []TrafficCaller `json:"callers"`
}