Remote / foldkit-remote-server

When the server fails

A call that does not succeed tells its caller one of two kinds of thing, and which is decided by the type of the error where it is made, never by reading its message:

What happenedWhat the caller reads
Application refusal (refuse, forbid, unauthenticated, unmet, taken, invalid)the refusal's message and reason (or Forbidden / Unauthenticated)
RemoteServer.tell(message)message, as written
Bad request (unknown query/mutation, Schema mismatch, too many IDs, wrong protocol)a fixed sentence naming only what the request sent
Unclassified failure or defect in a Source, authorize, filter, or operatorInternal error, and an incident

So a failure nobody classified is this side's: its message and cause are reported as a ServerDefect diagnostic and never sent. A Source says which it means:

ts
import { Effect, Schema } from 'effect'
import { Entity } from 'foldkit-remote'
import { RemoteServer, RemoteServerError } from 'foldkit-remote-server'

const Report = Entity.make('Report', Schema.Struct({ id: Schema.String, total: Schema.Number }))

declare const building: (id: string) => boolean
declare const totals: (
  ids: ReadonlyArray<string>,
) => Promise<ReadonlyArray<{ readonly id: string; readonly total: number }>>

const ReportSource = RemoteServer.entity(Report, {
  read: ({ ids }) =>
    ids.some(building)
      ? // Words for whoever asked: sent as written.
        Effect.fail(RemoteServer.tell('That report is still being built'))
      : Effect.tryPromise({
          try: () => totals(ids),
          // What the driver said stays on this side: reported, never sent.
          catch: cause => new RemoteServerError({ message: 'The totals query failed', cause }),
        }).pipe(Effect.map(rows => rows.map(row => ({ id: row.id, values: row })))),
})

RemoteServer.tell takes text, not what was caught: an error's own message may say anything, so tell(caught) does not compile. Write what it says from what the caller may know.

The incident is 16 hex characters, made for each failure. The caller's error carries it ({ error: 'Internal error', incident } over JSON, the incident field of RemoteReadError, RemoteQueryError, RemoteMutationError and RemoteLiveError over RPC, and of a live stream's error frame), and the client reads it with RemoteData.incident(error). The report carries the same id, what was asked (during), and the cause (its stack lines left out here):

[foldkit-remote-server] incident 3f9c2a7be01d4c55: read Report failed on this side. No caller is told more of it than this id.
RemoteServerError: The totals query failed
  [cause]: Error: SQLITE_BUSY: database is locked

What this does not cover: a refusal's message, a forbid reason, an invariant's message and tell's text are sent as written, so nothing a caller may not know belongs in them; and a 400's error is the protocol Schema's own account of the request's payload. There is no switch that puts the cause in a response: read the report.

Reporting from an adapter or a scheduled job

A failure outside a handler has no caller's error to carry an incident: a job a cron trigger runs, or an adapter answering on a transport of its own. RemoteServer.report(during, cause) reports it as the server reports its own, a ServerDefect under a new incident, and answers the only thing that may go further: { message: 'Internal error', incident }.

ts
import { Effect } from 'effect'
import { RemoteServer } from 'foldkit-remote-server'

declare const publishDue: Effect.Effect<void, unknown>
declare const remember: (shown: string) => Effect.Effect<void>

export const job = publishDue.pipe(
  Effect.catchCause(cause =>
    Effect.flatMap(RemoteServer.report('publish due', cause), ({ message, incident }) =>
      // What a reader of the job's outcome may see: the words and the id.
      remember(`${message} (incident ${incident})`),
    ),
  ),
)

It takes what was caught, or a Cause, and returns nothing of either. It reports through the Diagnostics.Reporter of the Effect it runs in.