Remote / foldkit-remote-server

foldkit-remote-server

The server-side interpreter for foldkit-remote.

A Remote client sends semantic requirements — entity ids, selected fields, query windows, mutations, and live requirements. foldkit-remote-server turns those requirements into calls to application-owned Sources, enforces field-level read authorization while the field names are still known, and normalizes the results back into the patches the client cache understands.

The central pipeline is:

Remote requirement
      |
      v
RemoteServer handlers
      |
      +-- validate protocol / input
      +-- filter fields by Entity + principal
      +-- group and de-duplicate reads
      |
      v
application Source
      |
      v
normalized Remote result
      |
      v
Remote client -> Message -> Data.reduce -> Model

A Source is deliberately small: it says how your application reads one Entity, runs one Query or Mutation, or produces one live stream. The package does not own HTTP, WebSockets, authentication, or a database connection; answer answers a JSON request a server you run received. Authentication resolves a principal outside this package; database/API clients remain Effect requirements of the Sources that use them.

Use this package when the server is yours and you want the selections declared by foldkit-remote to survive all the way to the data boundary instead of turning back into hand-written per-screen endpoints.

What this package owns

client owns
  which server facts are required

foldkit-remote-server owns
  requirement interpretation
  field authorization
  read grouping / de-duplication
  nested selection traversal
  normalized wire results

application Sources own
  how those facts are actually loaded or changed

Effect RPC / application owns
  transport + serialization + authentication

That separation matters. RemoteServer can decide that a client may read Project.name but not Project.privateNotes; only your Source knows whether that field comes from Postgres, another service, an in-memory index, or something else.

Install

bash
pnpm add foldkit-remote-server

effect is a peer dependency; foldkit-remote comes with the package. foldkit-remote-drizzle is an optional Source compiler for Drizzle-backed entities and queries.