Cache

Aidbox keeps a set of in-memory caches per process: introspected access tokens, FHIR Artifact Registry (FAR) resolved canonicals, route definitions, secrets, and a few smaller caches. Most cache invalidations happen automatically — see Cache replication for how this works in highly available deployments. The $drop-cache operation forces a manual refresh.

Drop cache operation

Drops every in-memory cache on every replica. Intended for testing and debugging — when you want a known-cold cache, or to check whether behaviour you are seeing comes from a stale entry.

Writes through Aidbox invalidate the caches they affect, so this is not part of normal operation. Reach for it when something changed outside Aidbox — contents edited directly in the database, or a key rotated on an external token introspection endpoint — and you need the caches to forget what they hold.

POST /$drop-cache

The response is 200 OK with no body.

What gets cleared

• Introspected access token cache
• FAR-resolved canonical resources (StructureDefinitions, ValueSets, CodeSystems, ConceptMaps, SearchParameters)
• Compiled FHIR Schemas
• Route definitions and operation handlers
• Secrets resolved from external vaults

Multi-replica deployments

$drop-cache clears the caches of every replica, not only the one that receives the request. It publishes the drop over the same PostgreSQL LISTEN / NOTIFY channel that cache replication uses, and every replica subscribes to it.

One call is therefore enough: send it through the load balancer and it reaches all pods. There is no need to address each replica directly.

Propagation is asynchronous — a replica drops its caches when it receives the notification, normally within a second.