Remote / foldkit-remote-server
How a read resolves
A client selection can request several IDs and nested relations at once. Before
calling your Sources, the handler groups requirements by entity, takes the union
of requested fields across screens, keeps only declared fields that pass
authorize, and batches de-duplicated IDs into one read({ ids, fields,
windows?, principal }) call per entity.
If any selected field is a relation reference, the handler follows the returned IDs level by level into the target Entity's Source until every selected branch is resolved, then returns normalized patches.
Key rules enforced by every Entity Source:
- Undeclared fields are dropped before
authorizeorreadruns. Fields, relations, and derived members are all declared on the Entity, so a relation such asowneris authorized and followed like any field. - Requested fields are matched as own properties returned by your Source, so
constructoror__proto__are settled rather than read fromObject.prototype. authorizecan only narrow requested fields; it never adds fields the client did not ask for.- A Source may omit a requested field; any omitted field is settled as unavailable so the client stops re-requesting it.
- Shared IDs across multiple selections are fetched once, and relation targets are batched level by level without redundant fetches.
- A relation the principal may not read is skipped without following its target.
authorizeruns once per field across all rows;filterruns per record afterreadand may request extra fields (such as an owner ID) needed to decide visibility. Members removed byfilterare settled as unavailable.foldkit-guardbuildsfilterrules from member guards.- A Source or Query Source may declare
visible(from a Drizzle binding orRemoteServer.memory'sreadable) so startup checks likeGuardServer.validatecan verify row-level rules.
Keep your Source queries tight by projecting only fields in your database or
API call: the handler strips extra keys on return, and projecting at the data
boundary avoids wasted work.
Nested selections
When a client projects Project:p1 { id, name, owner { id, name } }, the
Project Source returns owner as a reference (User:u7) rather than joining
or inlining the user row.
RemoteServer collects all owner refs across the batch and requests their
selected fields from UserSource in one batched level. The Sources never call
each other recursively: RemoteServer handles traversal, depth limits,
batching, and de-duplication while each Source answers only for its own Entity.