Remote / foldkit-remote-server/fetch

FetchConfig

interface · packages/remote-server/src/fetch.ts:38

interface FetchConfig<P, R, Env, RP = never> {
  readonly server: ServerDefinition<P, R>
  readonly resolvePrincipal: (
    request: Request,
    env: Env,
  ) => Effect.Effect<P, RemoteUnauthenticated, RP>
  readonly layer: (env: Env) => Layer.Layer<R | RP>
  readonly path?: string | undefined
  readonly headers?:
    ((principal: P) => Readonly<Record<string, string>>) | undefined
  readonly live?: LiveHub<P, R> | undefined
  readonly revalidate?:
    | {
        readonly every: Duration.Input
        readonly key?: ((principal: P) => unknown) | undefined
      }
    | undefined
  readonly liveHeartbeat?: Duration.Input | undefined
  readonly maxIdsPerEntity?: number | undefined
  readonly maxDepth?: number | undefined
}

What serveFetch needs of the host runtime, per request.

Members

FetchConfig.server

property · packages/remote-server/src/fetch.ts:40

readonly server: ServerDefinition<P, R>

The server definition, as RemoteServer.make built it.

FetchConfig.resolvePrincipal

property · packages/remote-server/src/fetch.ts:46

readonly resolvePrincipal: (
  request: Request,
  env: Env,
) => Effect.Effect<P, RemoteUnauthenticated, RP>

Who this request is, from the request and the environment. Fails with RemoteServer.unauthenticated(reason?) to refuse the caller: a 401. What it needs (a session store, an auth service) comes from layer.

FetchConfig.layer

property · packages/remote-server/src/fetch.ts:55

readonly layer: (env: Env) => Layer.Layer<R | RP>

What the Sources and the resolver need, from the environment. Built per request, so kept cheap, and closed when the answer is sent, or, for a live stream, when the stream ends.

FetchConfig.path

property · packages/remote-server/src/fetch.ts:57

readonly path?: string | undefined

The path answered; anything else is a 404. Default /remote.

FetchConfig.headers

property · packages/remote-server/src/fetch.ts:64

readonly headers?:
  ((principal: P) => Readonly<Record<string, string>>) | undefined

Headers every answer to principal carries, a live stream's included; a refusal has no principal and carries none. Whom the request was answered as, say, for a client to repeat (foldkit-auth's AuthServer.answered).

FetchConfig.live

property · packages/remote-server/src/fetch.ts:66

readonly live?: LiveHub<P, R> | undefined

A hub whose changed/deleted signals reach the live streams this serves.

FetchConfig.revalidate

property · packages/remote-server/src/fetch.ts:78

readonly revalidate?:
  | {
      readonly every: Duration.Input
      readonly key?: ((principal: P) => unknown) | undefined
    }
  | undefined

Asks resolvePrincipal again, of the same request, every every while a live stream is open. A refusal ends the stream with Unauthenticated, which the client reads as a lost session; a principal whose key differs from the one the stream opened with (Policy.keyOf, as liveHub's key) ends it as a live error, which the client opens again after, as the new principal; without key only a refusal ends it. Without revalidate a stream serves the principal it opened with until it closes, a revoked session included. every must be longer than zero: each pass asks the session store.

FetchConfig.liveHeartbeat

property · packages/remote-server/src/fetch.ts:85

readonly liveHeartbeat?: Duration.Input | undefined

A heartbeat comment every this often, keeping idle streams alive through proxies. Default 15 seconds.

FetchConfig.maxIdsPerEntity

property · packages/remote-server/src/fetch.ts:87

readonly maxIdsPerEntity?: number | undefined

A read batch may not name more ids of one entity than this; default 1000.

FetchConfig.maxDepth

property · packages/remote-server/src/fetch.ts:89

readonly maxDepth?: number | undefined

A nested selection may not reach further than this many levels; default 8.