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 happened | What 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 operator | Internal 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:
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 lockedWhat 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 }.
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.