acrylblends 0.7.2 → 0.7.4

package/docs/framework/helpers/streaming.md

@@ -81,6 +81,126 @@ app.get('/sse', async (c) => {
 })
 ```
 
+## Cancelling work when the client leaves
+
+A reader that closes the tab, loses the network or presses a Stop button should not leave your server working for nobody (a request to a paid model, a database scan). There are two signals, and they are not the same:
+
+- **`c.req.raw.signal`** is the request's `AbortSignal`. It aborts when the client goes away. Pass it to anything that takes a `signal`, such as `fetch`, and the work stops with the client. This is the one to use for cancelling work.
+- **`stream.onAbort(callback)`** and **`stream.aborted`** belong to the response stream. They report that the *reader of the response* was cancelled. Measured: when you call `app.request()` with a `signal` and abort it, `c.req.raw.signal` aborts and `stream.aborted` stays `false`; when the reader of the response body is cancelled, `stream.onAbort` fires and `c.req.raw.signal` does not. On a real connection the request signal is what fired when a browser aborted its `fetch`. Use `c.req.raw.signal` for the work, and `stream.onAbort` for cleanup of the stream itself.
+
+An abort event that has already fired does not fire again, so check `signal.aborted` before you wait for it:
+
+```ts
+const waitForAbort = (signal: AbortSignal) =>
+  signal.aborted
+    ? Promise.resolve()
+    : new Promise<void>((resolve) => signal.addEventListener('abort', () => resolve(), { once: true }))
+```
+
+Keep what you have when the client leaves by saving it in a `finally` block: the stream callback runs to the end whether or not the client is still there.
+
+## Streaming an answer from a model
+
+A chat answer that arrives token by token is a `streamSSE` response that reads a streaming upstream. This server route calls an OpenAI-compatible chat completions API (`stream: true`), forwards each piece as an event, and cancels the upstream request when the client leaves. The key comes from the environment and is never written anywhere.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { streamSSE } from 'acrylblends/streaming'
+
+/** The pieces of an OpenAI-compatible streaming answer: each `data:` line holds a JSON chunk, and `[DONE]` ends it. */
+async function* modelPieces(messages: { role: string; content: string }[], signal: AbortSignal): AsyncGenerator<string> {
+  const key = process.env.DEEPSEEK_API_KEY
+  if (!key) throw new Error('DEEPSEEK_API_KEY is not set')
+  const base = process.env.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com'
+  const response = await fetch(`${base}/chat/completions`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+    body: JSON.stringify({ model: process.env.DEEPSEEK_MODEL ?? 'deepseek-chat', messages, stream: true }),
+    signal,
+  })
+  if (!response.ok || !response.body) throw new Error(`the model service answered ${response.status}`)
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true })
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? ''
+    for (const line of lines) {
+      if (!line.startsWith('data:')) continue
+      const data = line.slice(5).trim()
+      if (data === '[DONE]') return
+      const piece = (JSON.parse(data) as { choices?: { delta?: { content?: string } }[] }).choices?.[0]?.delta?.content
+      if (piece) yield piece
+    }
+  }
+}
+
+const app = new Acryl()
+
+app.post('/api/chat', async (c) => {
+  const { message } = await c.req.json<{ message: string }>()
+  const signal = c.req.raw.signal // aborts when the client goes away
+  return streamSSE(c, async (stream) => {
+    let answer = ''
+    try {
+      for await (const piece of modelPieces([{ role: 'user', content: message }], signal)) {
+        answer += piece
+        // JSON-encode the piece: a piece may contain a newline, which would end an SSE `data:` line.
+        await stream.writeSSE({ event: 'token', data: JSON.stringify(piece) })
+      }
+      await stream.writeSSE({ event: 'done', data: '{}' })
+    } catch (error) {
+      if (!signal.aborted) await stream.writeSSE({ event: 'error', data: JSON.stringify('The model could not answer.') })
+    } finally {
+      console.log(`kept ${answer.length} characters`) // save what arrived, also when the client pressed Stop
+    }
+  })
+})
+```
+
+## Reading a POST event stream in the browser
+
+`EventSource` can only send a GET request. For a POST (a chat message), read the response body yourself; this function calls `on` for each event as it arrives:
+
+```ts
+async function readEvents(body: ReadableStream<Uint8Array>, on: (event: string, data: string) => void): Promise<void> {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) return
+    // Line endings may be CRLF; a \r at the end of a chunk is completed by the next chunk, so normalise the whole buffer.
+    buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll('\r\n', '\n')
+    const blocks = buffer.split('\n\n')
+    buffer = blocks.pop() ?? ''
+    for (const block of blocks) {
+      let event = 'message'
+      const data: string[] = []
+      for (const line of block.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim()
+        else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')) // the SSE spec strips one leading space only
+      }
+      on(event, data.join('\n'))
+    }
+  }
+}
+
+const controller = new AbortController() // controller.abort() is the Stop button
+const response = await fetch('/api/chat', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ message: 'Hello' }),
+  signal: controller.signal,
+})
+let answer = ''
+await readEvents(response.body!, (event, data) => {
+  if (event === 'token') answer += JSON.parse(data) as string
+})
+```
+
+A complete chat component built on this is in the `chat` template of `create-acrylblends` (`npm create acrylblends@latest my-chat -- --template chat`).
+
 ## Error Handling
 
 The third argument of the streaming helper is an error handler.

package/docs/framework/helpers/websocket.md

@@ -1,11 +1,11 @@
 # WebSocket Helper
 
 WebSocket Helper is a helper for server-side WebSockets in Acryl applications.
-The Node.js adapter is available; the others are not yet available.
+The Node.js, Cloudflare Workers and Bun adapters are available.
 
 ## Import
 
-Only the Node.js adapter, `acrylblends/node-server`, is available today. The adapters for the other platforms (Cloudflare Workers, Bun, Vercel, AWS Lambda, Netlify and Lambda@Edge) are **not yet available**; their imports are shown for completeness and are not checked by the docs tests.
+The Node.js adapter (`acrylblends/node-server`), the Cloudflare Workers adapter (`acrylblends/cloudflare-workers`) and the Bun adapter (`acrylblends/bun`) provide `upgradeWebSocket`. The other platforms have no WebSocket support in their adapters. The Bun adapter is checked on Bun in the framework's release check; its examples below are not type-checked by the docs tests, which run without Bun's types.
 
 **Cloudflare Workers**
 

package/docs/framework/middleware/builtin/ip-restriction.md

@@ -31,7 +31,7 @@ app.use(
 app.get('/', (c) => c.text('Acryl!'))
 ```
 
-Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. For a runtime whose adapter is not yet available there is no `getConnInfo` to pass yet.
+Pass the `getConninfo` from the [ConnInfo helper](../../helpers/conninfo.md) appropriate for your environment as the first argument of `ipRestriction`. Every adapter has one (`acrylblends/bun`, `acrylblends/aws-lambda`, `acrylblends/node-server` and the others).
 
 ## Rules
 

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "cdc083e1bbaedaeafa7494fe646bdb202ce86d09"
+    "commit": "eada6fb06a5cafb6c2c92a97effeba567dbd44ba"
   },
-  "files": 91,
-  "digest": "sha256:964e5ff58d487ce53394469d359a251265a3ef093354f55b6b4c47c55051774b"
+  "files": 98,
+  "digest": "sha256:396f882ac7b612455edc59961c52472fadc5f95ea1a778208e7edd860e4e6727"
 }

package/lib/aws-lambda.d.ts

@@ -0,0 +1,324 @@
+import { Y as Schema, v as Env } from "./context-DS3fYyG-.js";
+import { r as GetConnInfo } from "./types-Dv_nV2cv.js";
+import { t as Acryl } from "./app-D8riatvv.js";
+
+//#region ../../plugins/acryl-router/src/core/adapter/aws-lambda/types.d.ts
+interface CognitoIdentity {
+  cognitoIdentityId: string;
+  cognitoIdentityPoolId: string;
+}
+interface ClientContext {
+  client: ClientContextClient;
+  Custom?: any;
+  env: ClientContextEnv;
+}
+interface ClientContextClient {
+  installationId: string;
+  appTitle: string;
+  appVersionName: string;
+  appVersionCode: string;
+  appPackageName: string;
+}
+interface ClientContextEnv {
+  platformVersion: string;
+  platform: string;
+  make: string;
+  model: string;
+  locale: string;
+}
+/**
+ * {@link Handler} context parameter.
+ * See {@link https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html AWS documentation}.
+ */
+interface LambdaContext {
+  callbackWaitsForEmptyEventLoop: boolean;
+  functionName: string;
+  functionVersion: string;
+  invokedFunctionArn: string;
+  memoryLimitInMB: string;
+  awsRequestId: string;
+  logGroupName: string;
+  logStreamName: string;
+  identity?: CognitoIdentity | undefined;
+  clientContext?: ClientContext | undefined;
+  getRemainingTimeInMillis(): number;
+}
+type Callback<TResult = any> = (error?: Error | string | null, result?: TResult) => void;
+type Handler<TEvent = any, TResult = any> = (event: TEvent, context: LambdaContext, callback: Callback<TResult>) => void | Promise<TResult>;
+interface ClientCert {
+  clientCertPem: string;
+  subjectDN: string;
+  issuerDN: string;
+  serialNumber: string;
+  validity: {
+    notBefore: string;
+    notAfter: string;
+  };
+}
+interface Identity {
+  accessKey?: string;
+  accountId?: string;
+  caller?: string;
+  cognitoAuthenticationProvider?: string;
+  cognitoAuthenticationType?: string;
+  cognitoIdentityId?: string;
+  cognitoIdentityPoolId?: string;
+  principalOrgId?: string;
+  sourceIp: string;
+  user?: string;
+  userAgent: string;
+  userArn?: string;
+  clientCert?: ClientCert;
+}
+interface ApiGatewayRequestContext {
+  accountId: string;
+  apiId: string;
+  authorizer: {
+    claims?: unknown;
+    scopes?: unknown;
+  };
+  domainName: string;
+  domainPrefix: string;
+  extendedRequestId: string;
+  httpMethod: string;
+  identity: Identity;
+  path: string;
+  protocol: string;
+  requestId: string;
+  requestTime: string;
+  requestTimeEpoch: number;
+  resourceId?: string;
+  resourcePath: string;
+  stage: string;
+}
+interface Authorizer {
+  iam?: {
+    accessKey: string;
+    accountId: string;
+    callerId: string;
+    cognitoIdentity: null;
+    principalOrgId: null;
+    userArn: string;
+    userId: string;
+  };
+  jwt?: {
+    claims: Record<string, string | number | boolean | string[]>;
+    scopes: string[] | null;
+  };
+  /**
+   * The `context` object returned by a Lambda (REQUEST) authorizer.
+   * It is `null` when the authorizer returns no context.
+   */
+  lambda?: Record<string, unknown> | null;
+}
+interface ApiGatewayRequestContextV2 {
+  accountId: string;
+  apiId: string;
+  authentication: null;
+  authorizer: Authorizer;
+  domainName: string;
+  domainPrefix: string;
+  http: {
+    method: string;
+    path: string;
+    protocol: string;
+    sourceIp: string;
+    userAgent: string;
+  };
+  requestId: string;
+  routeKey: string;
+  stage: string;
+  time: string;
+  timeEpoch: number;
+}
+interface ALBRequestContext {
+  elb: {
+    targetGroupArn: string;
+  };
+}
+interface LatticeRequestContextV2 {
+  serviceNetworkArn: string;
+  serviceArn: string;
+  targetGroupArn: string;
+  region: string;
+  timeEpoch: string;
+  identity: {
+    sourceVpcArn?: string;
+    type?: string;
+    principal?: string;
+    principalOrgID?: string;
+    sessionName?: string;
+    x509IssuerOu?: string;
+    x509SanDns?: string;
+    x509SanNameCn?: string;
+    x509SanUri?: string;
+    x509SubjectCn?: string;
+  };
+}
+//#endregion
+//#region ../../plugins/acryl-router/src/core/adapter/aws-lambda/handler.d.ts
+type LambdaEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2 | ALBProxyEvent | LatticeProxyEventV2;
+interface LatticeProxyEventV2 {
+  version: string;
+  path: string;
+  method: string;
+  headers: Record<string, string[] | undefined>;
+  queryStringParameters: Record<string, string[] | undefined>;
+  body: string | null;
+  isBase64Encoded: boolean;
+  requestContext: LatticeRequestContextV2;
+}
+interface APIGatewayProxyEventV2 {
+  version: string;
+  routeKey: string;
+  headers: Record<string, string | undefined>;
+  multiValueHeaders?: undefined;
+  cookies?: string[];
+  rawPath: string;
+  rawQueryString: string;
+  body: string | null;
+  isBase64Encoded: boolean;
+  requestContext: ApiGatewayRequestContextV2;
+  queryStringParameters?: {
+    [name: string]: string | undefined;
+  };
+  pathParameters?: {
+    [name: string]: string | undefined;
+  };
+  stageVariables?: {
+    [name: string]: string | undefined;
+  };
+}
+interface APIGatewayProxyEvent {
+  version: string;
+  httpMethod: string;
+  headers: Record<string, string | undefined>;
+  multiValueHeaders?: {
+    [headerKey: string]: string[];
+  };
+  path: string;
+  body: string | null;
+  isBase64Encoded: boolean;
+  queryStringParameters?: Record<string, string | undefined>;
+  requestContext: ApiGatewayRequestContext;
+  resource: string;
+  multiValueQueryStringParameters?: {
+    [parameterKey: string]: string[];
+  };
+  pathParameters?: Record<string, string>;
+  stageVariables?: Record<string, string>;
+}
+interface ALBProxyEvent {
+  httpMethod: string;
+  headers?: Record<string, string | undefined>;
+  multiValueHeaders?: Record<string, string[] | undefined>;
+  path: string;
+  body: string | null;
+  isBase64Encoded: boolean;
+  queryStringParameters?: Record<string, string | undefined>;
+  multiValueQueryStringParameters?: {
+    [parameterKey: string]: string[];
+  };
+  requestContext: ALBRequestContext;
+}
+type WithHeaders = {
+  headers: Record<string, string | string[]>;
+  multiValueHeaders?: undefined;
+};
+type WithMultiValueHeaders = {
+  headers?: undefined;
+  multiValueHeaders: Record<string, string[]>;
+};
+type APIGatewayProxyResult = {
+  statusCode: number;
+  statusDescription?: string;
+  body: string;
+  cookies?: string[];
+  isBase64Encoded: boolean;
+} & (WithHeaders | WithMultiValueHeaders);
+declare const streamHandle: <E extends Env = Env, S extends Schema = {}, BasePath extends string = "/">(app: Acryl<E, S, BasePath>) => Handler;
+type HandleOptions = {
+  isContentTypeBinary: ((contentType: string) => boolean) | undefined;
+};
+/**
+ * Converts a Acryl application to an AWS Lambda handler.
+ *
+ * Accepts events from API Gateway (v1 and v2), Application Load Balancer (ALB),
+ * and Lambda Function URLs.
+ *
+ * @param app - The Acryl application instance
+ * @param options - Optional configuration
+ * @param options.isContentTypeBinary - A function to determine if the content type is binary.
+ *                                      If not provided, the default function will be used.
+ * @returns Lambda handler function
+ *
+ * @example
+ * ```js
+ * import { Acryl } from 'acrylblends'
+ * import { handle } from 'acrylblends/aws-lambda'
+ *
+ * const app = new Acryl()
+ *
+ * app.get('/', (c) => c.text('Hello from Lambda'))
+ * app.get('/json', (c) => c.json({ message: 'Hello JSON' }))
+ *
+ * export const handler = handle(app)
+ * ```
+ *
+ * @example
+ * ```js
+ * // With custom binary content type detection
+ * import { handle, defaultIsContentTypeBinary } from 'acrylblends/aws-lambda'
+ * export const handler = handle(app, {
+ *   isContentTypeBinary: (contentType) => {
+ *     if (defaultIsContentTypeBinary(contentType)) {
+ *       // default logic same as prior to v4.8.4
+ *       return true
+ *     }
+ *     return contentType.startsWith('image/') || contentType === 'application/pdf'
+ *   }
+ * })
+ * ```
+ */
+declare const handle: <E extends Env = Env, S extends Schema = {}, BasePath extends string = "/">(app: Acryl<E, S, BasePath>, {
+  isContentTypeBinary
+}?: HandleOptions) => (<L extends LambdaEvent>(event: L, lambdaContext?: LambdaContext) => Promise<APIGatewayProxyResult & (L extends {
+  multiValueHeaders: Record<string, string[]>;
+} ? WithMultiValueHeaders : WithHeaders)>);
+/**
+ * Check if the given content type is binary.
+ * This is a default function and may be overwritten by the user via `isContentTypeBinary` option in handler().
+ * @param contentType The content type to check.
+ * @returns True if the content type is binary, false otherwise.
+ */
+declare const defaultIsContentTypeBinary: (contentType: string) => boolean;
+//#endregion
+//#region ../../plugins/acryl-router/src/core/adapter/aws-lambda/conninfo.d.ts
+/**
+ * Get connection information from AWS Lambda
+ *
+ * Extracts client IP from various Lambda event sources:
+ * - API Gateway v1 (REST API): requestContext.identity.sourceIp
+ * - API Gateway v2 (HTTP API/Function URLs): requestContext.http.sourceIp
+ * - ALB: Falls back to x-forwarded-for header
+ *
+ * @param c - Context
+ * @returns Connection information including remote address
+ * @example
+ * ```ts
+ * import { Acryl } from 'acrylblends'
+ * import { handle, getConnInfo } from 'acrylblends/aws-lambda'
+ *
+ * const app = new Acryl()
+ *
+ * app.get('/', (c) => {
+ *   const info = getConnInfo(c)
+ *   return c.text(`Your IP: ${info.remote.address}`)
+ * })
+ *
+ * export const handler = handle(app)
+ * ```
+ */
+declare const getConnInfo: GetConnInfo;
+//#endregion
+export { type ALBRequestContext, type APIGatewayProxyResult, type ApiGatewayRequestContext, type ApiGatewayRequestContextV2, type LambdaContext, type LambdaEvent, defaultIsContentTypeBinary, getConnInfo, handle, streamHandle };