Building Cancellable API Routes with Jeston's RequestContext

Cancellation is a production concern, not an implementation detail. A client can disconnect, a request can exceed its deadline, or a response can close before downstream work finishes. If database calls, model clients, storage operations, or streams continue running anyway, the application spends resources on work nobody will receive.

Jeston makes cancellation explicit through RequestContext.signal. Every Node request receives an AbortSignal that is aborted when the client disconnects, the request deadline expires, or the response closes.

Pass the signal downstream

A route can pass the signal into application services:

import type { ApiHandler } from '@kvantjs/jeston';

export const POST: ApiHandler = async ({ body, signal }) => {
  await validateAndPersist(body, { signal });
  return { status: 201, json: { created: true } };
};

The service layer should preserve that contract instead of creating an unrelated controller-level timeout. Database drivers, model clients, storage adapters, and custom streaming code can then stop work when the request is no longer active.

Streaming follows the same rule

Jeston supports AsyncIterable<Uint8Array> responses for NDJSON, server-sent events, token output, progress, and other byte protocols. A streaming endpoint can check the same signal while producing output:

export async function POST({ signal }: RequestContext) {
  async function* progress() {
    yield new TextEncoder().encode('{"event":"started"}\n');
    await runEvaluation({ signal });
    yield new TextEncoder().encode('{"event":"completed"}\n');
  }

  return {
    stream: progress(),
    headers: { 'Content-Type': 'application/x-ndjson' },
  };
}

This is particularly useful for AI-related applications. Jeston can provide a deterministic HTTP and job boundary around agents, inference, evaluation, or training orchestration, while the application remains responsible for provider selection, data governance, consent, retention, evaluation, and recovery.

Reliable API behavior is a system property

Cancellation is one part of a broader request contract. Jeston also provides bounded request bodies, stable malformed-JSON errors, request deadlines, abort propagation, automatic OPTIONS behavior, safe HEAD handling, and incremental byte streams. These primitives reduce the number of edge cases each application has to reimplement.

The result is not magic reliability. It is a clear place to attach timeouts, cleanup, and observability so that production behavior can be tested rather than assumed.

Explore the API contracts in the Jeston repository.