GateKeeper — Overview

What it is

GateKeeper is the access-control layer in front of the racing data APIs. Every external client (e.g. CWS, WSB) that wants meetings, racecards, speed maps, or results data goes through GateKeeper first. On every request it answers one question: "Is this specific client allowed to see this specific piece of data?"

Without it, that restriction would be hardcoded or checked ad hoc in each data API. GateKeeper centralizes it: one place to define what a client can see, one place to change it, and downstream APIs just ask GateKeeper (or read the cache it maintains) instead of reimplementing the logic.

The problem it solves

A client is never "all or nothing" — it might be allowed only AU data, only meetings (not speed maps), everything except one venue under a data dispute, or a 30-day trial add-on on top of its normal plan. Multiplied across dozens of clients, hardcoding this becomes unmanageable. GateKeeper turns each rule into data (a package or an override) instead of code, so granting, changing, or revoking access is an admin action, not a deployment.

Key concepts

Term	Meaning
Customer	An external client granted API access (e.g. CWS, WSB), identified by a client_guid sent on every request.
Token (secret key)	The password half of a customer's credentials. Multiple tokens per customer are independently revocable.
Package	A named, reusable bundle of permission rules, assignable to any number of customers.
Subscription	The time-bound link between a customer and a package (start_date/optional end_date).
Override	A one-off grant or revoke for a single customer, outside any package. Overrides always win over packages.
Effective entitlement	The computed answer for a customer: union of their packages' grants, plus grant overrides, minus active revoke overrides. This is what's checked on every request.

How a request is protected

1. A client calls a protected endpoint (e.g. /v1/meetings) with X-Client-Guid + X-Api-Secret headers.
2. GateKeeper validates both are present, active, and belong together — a leaked secret replayed under a different client-guid is rejected.
3. It resolves the customer's effective entitlement (from packages + overrides, kept warm in a two-tier cache) and checks whether the requested country/discipline/data-type/venue is covered.
4. Allowed → request proceeds. Not allowed → rejected, no data returned.
5. Every request is logged asynchronously for auditing, off the response's critical path.

Admin changes (granting a package, adding an override, revoking a token) propagate to the cache via pub/sub, so they take effect in milliseconds — no TTL wait, no deployment.

Solution layout

GateKeeper.Core     entities, EffectiveEntitlement/EntitlementScope, resolver logic — no external deps
GateKeeper.Data     EF Core DbContext, entity configurations, repositories (MySQL via Pomelo)
GateKeeper.Cache    Redis + IMemoryCache two-tier cache, pub/sub invalidation
GateKeeper.Admin    GateKeeperAdminService — the only writer of customers/tokens/subscriptions/overrides
GateKeeper.Api      the runnable host: middleware pipeline + /v1/meetings + /admin/* HTTP endpoints
GateKeeper.AdminUI  Blazor Server admin UI, calls GateKeeperAdminService in-process (no HTTP hop)

Dependency direction: Core → Data → Cache → Admin → Api / AdminUI. Core has no external dependencies, which is what makes the resolver logic unit-testable without a database.

How it's administered

Onboarding a new client: create the customer (generates its client_guid) → issue a secret key (shown once) → assign the matching package(s) → hand off both credentials.

Day-to-day, via the Admin UI or Admin API: adjust a customer's packages, add a temporary override, rotate/revoke a token, check usage, or remove a client. Adding a new data type or restriction axis is a configuration change in GateKeeper, not a code change.

Deeper technical reference

See Architecture for the data model, entitlement resolution algorithm, caching strategy, and request pipeline; Quick Reference for the HTTP API, configuration, and run commands; and Known Issues for discrepancies found against the original design doc.