basalt / drives/src / DriveNotificationRoutes
Interface: DriveNotificationRoutes
Defined in: drives/src/routes.ts:78
Properties
connections
> connections: DriveConnectionCandidates
Defined in: drives/src/routes.ts:88
Candidate connections for an inbound notification.
For a per-tenant callback URL, an array or a resolver that reads that tenant's rows. For Dropbox — whose webhook is registered once per app — a resolver that looks connections up by (provider, accountIds); see DriveConnectionCandidates for why that cross-tenant lookup is safe and why it stays the app's query.
maxBytes?
> optional maxBytes?: number
Defined in: drives/src/routes.ts:102
Most bytes of body to read. Over it: 413. Default 64 KiB.
onChange
> onChange: (connections, query) => void | Promise<void>
Defined in: drives/src/routes.ts:96
Called when a verified notification means there is new work.
Enqueue; never sync inline. Dropbox retries and eventually disables a webhook URI that is slow, and a notification can fan out to several connections. This is the seam where @basaltkit/queue belongs.
Parameters
connections
readonly DriveConnection[]
query
Returns
void | Promise<void>
rawBody?
> optional rawBody?: (request) => string | Buffer<ArrayBufferLike> | undefined
Defined in: drives/src/routes.ts:120
Overrides where the raw bytes come from. Almost nobody needs this.
The delivery route declares rawBody(), so @basaltkit/http hands it the untouched octets on Fastify, Express and Hono alike — that is the whole point of the marker, and it needs no wiring. This hook remains for the one shape it cannot reach: an app that terminates the request somewhere else (a serverless adapter, a proxy that re-frames the body) and holds the real bytes itself.
What it is not is a place to reconstruct them. Returning JSON.stringify(request.body) here re-creates the fail-every-delivery bug this route was built to make impossible: a signature covers the bytes that arrived, and a re-serialised object is a different message. Return the bytes or return nothing — the route fails closed with DRIVE_NOTIFICATION_INVALID rather than guess.
Parameters
request
Returns
string | Buffer<ArrayBufferLike> | undefined
replayGuard?
> optional replayGuard?: NotificationReplayGuard
Defined in: drives/src/routes.ts:98
Collapses duplicate deliveries. Back it with @basaltkit/cache in a cluster.
replayTtlMs?
> optional replayTtlMs?: number
Defined in: drives/src/routes.ts:100
Replay window. Default 5 minutes.