acrylblends 0.7.3 → 0.7.5

package/plugins/acryl-db/src/facade/schema.ts

@@ -0,0 +1,9 @@
+/** Validate a prefix before using it as part of a SQL identifier. */
+export function validateSchemaPrefix(prefix: string): void {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) {
+		throw new Error(`Invalid SQL schema prefix ${JSON.stringify(prefix)}`);
+	}
+	if (prefix.toLowerCase().startsWith("sqlite_")) {
+		throw new Error(`SQL schema prefix ${JSON.stringify(prefix)} is reserved`);
+	}
+}

package/plugins/acryl-db/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The `db` port: what an app's code sees of its relational database, whichever provider (`acryl-db-sqlite`, `acryl-db-postgres`) serves
+ * it. Plain code (an acrylblends app) opens a database with a provider's `openDb`; a Cordis plugin declares `inject: ['db']`, imports
+ * `acryl-db/cordis` for the `ctx.db` type, and never imports a driver.
+ *
+ * Bindings are positional `?` placeholders on every provider; a provider whose database spells them differently translates them.
+ * This entry imports nothing from Cordis, at runtime or in its types.
+ */
+
+/** The service name every `db` provider registers. */
+export const DB_SERVICE = 'db'
+
+/** The table that records an app's migration version. */
+export const MIGRATIONS_TABLE = '_migrations'
+
+export type { Db, DbExecutor, SqlValue } from './facade/database.ts'
+export { applyMigrations, type Migration } from './facade/migrations.ts'
+export { validateSchemaPrefix } from './facade/schema.ts'
+export { readMigrationFiles } from './migration-files.ts'

package/plugins/acryl-db/src/migration-files.ts

@@ -0,0 +1,31 @@
+/**
+ * An app's migrations as numbered SQL files: `migrations/001-notes.sql`, `002-tags.sql`, ... Each file is one migration, run as one
+ * `exec` (so it may hold several statements), numbered from 1 with no gaps.
+ */
+
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Migration } from './facade/migrations.ts'
+
+const FILE = /^(\d+)-[a-z0-9][a-z0-9-]*\.sql$/u
+
+/**
+ * Read every `NNN-name.sql` file of a folder, in number order.
+ * @throws when a `.sql` file is not named `NNN-name.sql`, or the numbers do not run 1, 2, 3, ... without gaps or repeats.
+ */
+export async function readMigrationFiles(folder: string | URL): Promise<Migration[]> {
+  const dir = typeof folder === 'string' ? folder : fileURLToPath(folder)
+  const files = (await readdir(dir)).filter(name => name.endsWith('.sql')).sort()
+  const numbered = files.map(name => {
+    const match = FILE.exec(name)
+    if (match?.[1] === undefined) throw new Error(`acryl-db: migration file ${name} in ${dir} must be named NNN-name.sql, like 001-notes.sql`)
+    return { name, version: Number(match[1]) }
+  }).sort((a, b) => a.version - b.version)
+  numbered.forEach((file, index) => {
+    if (file.version !== index + 1) {
+      throw new Error(`acryl-db: migration ${file.name} in ${dir} should be number ${String(index + 1)}; the files must be numbered 1, 2, 3, ... with no gaps or repeats`)
+    }
+  })
+  return Promise.all(numbered.map(async file => ({ version: file.version, statements: [await readFile(join(dir, file.name), 'utf8')] })))
+}

package/plugins/acryl-db/upstream.json

@@ -0,0 +1,18 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-db",
+    "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 0,
+  "digest": "sha256:51e5613457498bfab7c281e0c6443c4f7535401c16520ac44624dc8791a90fa6",
+  "testsNotRun": {},
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-db-sqlite/LICENSE

@@ -0,0 +1,47 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The files under src/facade and tests/facade are derived from the SQLite facade of chord in pi (https://github.com/earendil-works/pi, packages/chord, commit d5b3de22d0e24a3e9c38a9410d3329b099717283), used under this license:
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/acryl-db-sqlite/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "acryl-db-sqlite",
+  "description": "The SQLite provider of the db port: one node:sqlite file in the app home (WAL), the app's numbered migrations applied on start, db provided to plugins. Vendored from ACRYL.",
+  "requires": ["acryl-db", "instance"],
+  "inject": [],
+  "provides": ["db"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "mount": "mount it after instance: root.plugin(dbSqlite, { migrations: 'migrations' }) with the migrations/ folder (001-name.sql, ...) next to src/; then a plugin that declares inject: ['db'] calls await ctx.db.all('SELECT ...', value)",
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+}

package/plugins/acryl-db-sqlite/src/facade/node.ts

@@ -0,0 +1,199 @@
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { StatementSync } from "node:sqlite";
+import { DatabaseSync } from "node:sqlite";
+import type { Db, DbExecutor, SqlValue } from "../../../acryl-db/src/index.ts";
+
+/** Node SQLite connection settings for a database file. */
+export type NodeSqliteDatabaseOptions = {
+	/** SQLite WAL auto-checkpoint threshold. SQLite and this adapter default to 1,000 pages; 0 disables it. */
+	readonly walAutoCheckpointPages?: number;
+	/** Time SQLite waits for a competing file lock. SQLite defaults to 0; this adapter defaults to 5,000 ms. */
+	readonly busyTimeoutMs?: number;
+};
+
+const DEFAULT_WAL_AUTO_CHECKPOINT_PAGES = 1_000;
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+
+type TransactionScope = { active: boolean };
+
+const ignore = (): void => {};
+
+/**
+ * Runs operations in call order. An operation starts immediately when nothing is running or waiting;
+ * otherwise it waits for everything before it. An asynchronous operation holds the queue until it settles.
+ */
+class SerialOperationQueue {
+	private tail: Promise<void> = Promise.resolve();
+	private pending = 0;
+
+	run<T>(operation: () => T): Promise<T> {
+		if (this.pending > 0) return this.enqueue(operation);
+		try {
+			return Promise.resolve(operation());
+		} catch (error) {
+			return Promise.reject(error);
+		}
+	}
+
+	runAsync<T>(operation: () => Promise<T>): Promise<T> {
+		if (this.pending > 0) return this.enqueue(operation);
+		this.pending++;
+		// Publish the barrier before the operation starts, so calls it makes synchronously wait behind it.
+		const { promise: barrier, resolve: releaseBarrier } = Promise.withResolvers<void>();
+		this.tail = barrier;
+		let started: Promise<T>;
+		try {
+			started = operation();
+		} catch (error) {
+			started = Promise.reject(error);
+		}
+		return started.finally(() => {
+			this.pending--;
+			releaseBarrier();
+		});
+	}
+
+	private enqueue<T>(operation: () => T | Promise<T>): Promise<T> {
+		this.pending++;
+		return this.release(this.tail.then(operation));
+	}
+
+	private release<T>(operation: Promise<T>): Promise<T> {
+		const settled = operation.finally(() => {
+			this.pending--;
+		});
+		this.tail = settled.then(ignore, ignore);
+		return settled;
+	}
+}
+
+/**
+ * Executes SQL on one connection. Prepared statements are cached per connection by SQL text, so the
+ * database and its transaction handles share them across transactions.
+ */
+abstract class NodeSqliteExecutor implements DbExecutor {
+	protected readonly database: DatabaseSync;
+	protected readonly statements: Map<string, StatementSync>;
+
+	constructor(database: DatabaseSync, statements: Map<string, StatementSync>) {
+		this.database = database;
+		this.statements = statements;
+	}
+
+	exec(sql: string): Promise<void> {
+		return this.runOperation(() => {
+			this.database.exec(sql);
+		});
+	}
+
+	run(sql: string, ...params: SqlValue[]): Promise<{ readonly changes: number }> {
+		return this.runOperation(() => ({ changes: Number(this.statement(sql).run(...params).changes) }));
+	}
+
+	get<T extends object>(sql: string, ...params: SqlValue[]): Promise<T | undefined> {
+		return this.runOperation(() => this.statement(sql).get(...params) as T | undefined);
+	}
+
+	all<T extends object>(sql: string, ...params: SqlValue[]): Promise<T[]> {
+		return this.runOperation(() => this.statement(sql).all(...params) as T[]);
+	}
+
+	protected abstract runOperation<T>(operation: () => T): Promise<T>;
+
+	private statement(sql: string): StatementSync {
+		let statement = this.statements.get(sql);
+		if (statement === undefined) {
+			statement = this.database.prepare(sql);
+			this.statements.set(sql, statement);
+		}
+		return statement;
+	}
+}
+
+class NodeSqliteTransaction extends NodeSqliteExecutor {
+	private readonly scope: TransactionScope;
+
+	constructor(database: DatabaseSync, statements: Map<string, StatementSync>, scope: TransactionScope) {
+		super(database, statements);
+		this.scope = scope;
+	}
+
+	protected async runOperation<T>(operation: () => T): Promise<T> {
+		if (!this.scope.active) throw new Error("SQLite transaction handle is no longer active");
+		return operation();
+	}
+}
+
+/** `Db` adapter backed by Node's built-in `node:sqlite`. */
+export class NodeSqliteDatabase extends NodeSqliteExecutor implements Db {
+	private readonly access = new SerialOperationQueue();
+	private closed = false;
+
+	constructor(database: DatabaseSync) {
+		super(database, new Map());
+	}
+
+	transaction<T>(callback: (transaction: DbExecutor) => Promise<T>): Promise<T> {
+		return this.access.runAsync(async () => {
+			this.database.exec("BEGIN IMMEDIATE");
+			const scope = { active: true };
+			try {
+				const result = await callback(new NodeSqliteTransaction(this.database, this.statements, scope));
+				scope.active = false;
+				this.database.exec("COMMIT");
+				return result;
+			} catch (error) {
+				scope.active = false;
+				try {
+					this.database.exec("ROLLBACK");
+				} catch (rollbackError) {
+					throw new AggregateError([error, rollbackError], "SQLite transaction failed and rollback failed");
+				}
+				throw error;
+			}
+		});
+	}
+
+	close(): Promise<void> {
+		return this.access.run(() => {
+			if (this.closed) return;
+			this.closed = true;
+			this.statements.clear();
+			try {
+				this.database.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+			} finally {
+				this.database.close();
+			}
+		});
+	}
+
+	protected runOperation<T>(operation: () => T): Promise<T> {
+		return this.access.run(operation);
+	}
+}
+
+/** Open and configure a Node-backed SQLite database facade. */
+export async function openNodeSqliteDatabase(
+	path: string,
+	options: NodeSqliteDatabaseOptions = {},
+): Promise<NodeSqliteDatabase> {
+	const checkpointPages = options.walAutoCheckpointPages ?? DEFAULT_WAL_AUTO_CHECKPOINT_PAGES;
+	const timeout = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+	if (path !== ":memory:") await mkdir(dirname(path), { recursive: true });
+	const database = new DatabaseSync(path, { timeout });
+	const adapter = new NodeSqliteDatabase(database);
+	try {
+		await adapter.exec("PRAGMA journal_mode = WAL");
+		await adapter.exec("PRAGMA synchronous = NORMAL");
+		await adapter.exec(`PRAGMA wal_autocheckpoint = ${checkpointPages}`);
+		return adapter;
+	} catch (error) {
+		try {
+			await adapter.close();
+		} catch {
+			// Preserve the configuration failure.
+		}
+		throw error;
+	}
+}

package/plugins/acryl-db-sqlite/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * The SQLite provider of the `db` port (spec 049 slice 1): one `node:sqlite` file, opened with the ported facade's settings (WAL,
+ * `synchronous = NORMAL`, a busy timeout), migrated, and provided as `db`. App plugins declare `inject: ['db']` and import types from
+ * `acryl-db` only, so replacing this row with another provider does not touch them. The plugin is a thin wrapper over `openDb`
+ * (`acryl-db-sqlite/open`), the same opening for code without Cordis.
+ *
+ * Unloading withdraws `db` first, so consumers stop calling, and then closes the file: the close waits for running operations and
+ * transactions, checkpoints the WAL and releases the file.
+ */
+
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { DB_SERVICE } from '../../acryl-db/src/index.ts'
+import type {} from '../../acryl-db/src/cordis.ts'
+import { openDb } from './open.ts'
+
+export { NodeSqliteDatabase, openNodeSqliteDatabase, type NodeSqliteDatabaseOptions } from './facade/node.ts'
+export { openDb, type OpenDb, type OpenDbOptions } from './open.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-db-sqlite'
+
+/**
+ * What this plugin reads of the runtime's optional `appInstance` service: its home folder. The service belongs to the runtime (and to an
+ * app's own instance plugin), so this plugin declares no type for it on Cordis' Context; it checks the one field it uses at runtime.
+ */
+interface AppHome {
+  readonly home: string
+}
+
+function isAppHome(value: unknown): value is AppHome {
+  return typeof value === 'object' && value !== null && 'home' in value && typeof value.home === 'string'
+}
+
+export interface Config {
+  path?: string
+  migrations?: string
+  busyTimeoutMs?: number
+  walAutoCheckpointPages?: number
+}
+
+export const Config: z<Config> = z.object({
+  path: z.string().description('The database file, absolute or relative to the app. Defaults to data.sqlite in the ACRYL app home; required where there is none.'),
+  migrations: z.string().description('A folder of NNN-name.sql files numbered from 1, absolute or relative to the app, applied in order on start.'),
+  busyTimeoutMs: z.natural().description('How long SQLite waits for a competing file lock, in milliseconds. Defaults to 5000.'),
+  walAutoCheckpointPages: z.natural().description('The WAL auto-checkpoint threshold in pages; 0 disables it. Defaults to 1000.'),
+})
+
+/** The file name used in the app home when `path` is not configured. */
+export const DEFAULT_FILE = 'data.sqlite'
+
+/** A configured path as a file path: absolute as given, relative to the Loader's base URL (the app) otherwise. */
+function resolveFromApp(ctx: Context, path: string, option: string): string {
+  if (path.startsWith('file:')) return fileURLToPath(path)
+  if (isAbsolute(path)) return path
+  const base = ctx.baseUrl
+  if (base === undefined || !base.startsWith('file:')) {
+    throw new Error(`acryl-db-sqlite: ${option} ${JSON.stringify(path)} is relative, but this app has no file base URL to resolve it from; give an absolute path`)
+  }
+  const appDir = base.endsWith('/') ? fileURLToPath(base) : dirname(fileURLToPath(base))
+  return resolve(appDir, path)
+}
+
+export async function apply(ctx: Context, rawConfig: Config = {}): Promise<void> {
+  const config = Config(rawConfig)
+  // The app home comes from the runtime's `appInstance` service when this runs inside an ACRYL app; a plain framework app names its file.
+  const appInstance: unknown = ctx.get('appInstance')
+  let file: string
+  if (config.path !== undefined) file = resolveFromApp(ctx, config.path, 'path')
+  else if (isAppHome(appInstance)) file = join(appInstance.home, DEFAULT_FILE)
+  else throw new Error('acryl-db-sqlite: no database path; set `path` in this row\'s config (there is no ACRYL app home to default to)')
+  const migrations = config.migrations === undefined ? undefined : resolveFromApp(ctx, config.migrations, 'migrations')
+  const options = {
+    path: file,
+    ...(migrations === undefined ? {} : { migrations }),
+    ...(config.busyTimeoutMs === undefined ? {} : { busyTimeoutMs: config.busyTimeoutMs }),
+    ...(config.walAutoCheckpointPages === undefined ? {} : { walAutoCheckpointPages: config.walAutoCheckpointPages }),
+  }
+
+  // Disposers run in reverse: the service is withdrawn before the file closes.
+  await ctx.effect(async function* () {
+    const opened = await openDb(options)
+    yield () => opened.close()
+    yield ctx.reflect.provide(DB_SERVICE, opened.db)
+  }, `acryl-db-sqlite: ${file}`)
+}

package/plugins/acryl-db-sqlite/src/open.ts

@@ -0,0 +1,61 @@
+/**
+ * The plain way to open the SQLite provider, for code without Cordis (an acrylblends app): `openDb({ path, migrations })` opens one
+ * `node:sqlite` file with the ported facade's settings (WAL, `synchronous = NORMAL`, a busy timeout) and foreign keys enforced, applies the
+ * numbered migrations, and resolves the `db` port with the function that closes it. The Cordis plugin is a thin wrapper over this, so both
+ * run one code path.
+ * This entry imports nothing from Cordis.
+ */
+
+import { applyMigrations, MIGRATIONS_TABLE, readMigrationFiles, type Db, type SqlValue } from '../../acryl-db/src/index.ts'
+import { openNodeSqliteDatabase } from './facade/node.ts'
+
+export type { Db, DbExecutor, SqlValue } from '../../acryl-db/src/index.ts'
+
+export interface OpenDbOptions {
+  /** The database file, its folder created if missing; `:memory:` for a database that lives until `close`. */
+  readonly path: string
+  /** A folder of `NNN-name.sql` files numbered from 1, as a path or a file URL, applied in order before `openDb` resolves. */
+  readonly migrations?: string | URL
+  /** How long SQLite waits for a competing file lock, in milliseconds. Defaults to 5000. */
+  readonly busyTimeoutMs?: number
+  /** The WAL auto-checkpoint threshold in pages; 0 disables it. Defaults to 1000. */
+  readonly walAutoCheckpointPages?: number
+}
+
+/** An open database: the port, and the one function that closes it. */
+export interface OpenDb {
+  readonly db: Db
+  /** Waits for running operations and transactions, checkpoints the WAL and releases the file. Calling it again does nothing. */
+  close(): Promise<void>
+}
+
+/**
+ * Open, configure and migrate a SQLite database.
+ * @throws when the migration files are misnamed or misnumbered, or a migration fails (the file is closed, and unchanged), or the
+ *   database's schema is newer than the migrations.
+ */
+export async function openDb(options: OpenDbOptions): Promise<OpenDb> {
+  const migrations = options.migrations === undefined ? [] : await readMigrationFiles(options.migrations)
+  const database = await openNodeSqliteDatabase(options.path, {
+    ...(options.busyTimeoutMs === undefined ? {} : { busyTimeoutMs: options.busyTimeoutMs }),
+    ...(options.walAutoCheckpointPages === undefined ? {} : { walAutoCheckpointPages: options.walAutoCheckpointPages }),
+  })
+  try {
+    // Off by default in SQLite, per connection, and ignored inside a transaction: set here, before the migrations' transaction. The port
+    // promises it (`ON DELETE CASCADE` works on every provider).
+    await database.exec('PRAGMA foreign_keys = ON')
+    await applyMigrations(database, migrations, { table: MIGRATIONS_TABLE })
+  } catch (error) {
+    await database.close()
+    throw error
+  }
+  // The port, not the adapter: the code that receives `db` gets no `close`, which belongs to whoever opened it.
+  const db: Db = {
+    exec: sql => database.exec(sql),
+    run: (sql, ...params) => database.run(sql, ...params),
+    get: <T extends object>(sql: string, ...params: SqlValue[]) => database.get<T>(sql, ...params),
+    all: <T extends object>(sql: string, ...params: SqlValue[]) => database.all<T>(sql, ...params),
+    transaction: work => database.transaction(work),
+  }
+  return { db, close: () => database.close() }
+}

package/plugins/acryl-db-sqlite/upstream.json

@@ -0,0 +1,21 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-db-sqlite",
+    "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 9,
+  "digest": "sha256:853af986073e5721c9b8fb5626b46bcd1ca8a6c5f936c4ac11fc3c21f3c5c0ef",
+  "testsNotRun": {
+    "tests/loader.spec.ts": "loads the plugin through the real Loader (@deepseek-ai/cordis-plugin-loader), which generated apps do not install; the plain opener it wraps is tested here by open.spec.ts and conformance.spec.ts",
+    "tests/plain-entry-imports.spec.ts": "a copy vendored into an app (with relative imports, no build of its own) has neither `lib/`; the app's own typecheck is what proves the copy names no Cordis type it does not provide."
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-inspect/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-inspect",
-    "commit": "e79bf3de59c700667ae617f5d367cc1fd2f8e037"
+    "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
   },
   "vendored": [
     "src",

package/plugins/acryl-node-server/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-node-server",
-    "commit": "e79bf3de59c700667ae617f5d367cc1fd2f8e037"
+    "commit": "4721bb00960fa4e157e6070c330cf87c148739fc"
   },
   "vendored": [
     "src",

package/plugins/acryl-router/src/core/adapter/aws-lambda/conninfo.ts

@@ -0,0 +1,73 @@
+import type { Context } from '../../context.ts'
+import type { GetConnInfo } from '../../helper/conninfo/index.ts'
+import type {
+  ApiGatewayRequestContext,
+  ApiGatewayRequestContextV2,
+  ALBRequestContext,
+} from './types.ts'
+
+type LambdaRequestContext =
+  | ApiGatewayRequestContext
+  | ApiGatewayRequestContextV2
+  | ALBRequestContext
+
+type Env = {
+  Bindings: {
+    requestContext: LambdaRequestContext
+  }
+}
+
+/**
+ * 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)
+ * ```
+ */
+export const getConnInfo: GetConnInfo = (c: Context<Env>) => {
+  const requestContext = c.env.requestContext
+
+  let address: string | undefined
+
+  // API Gateway v1 - has identity object
+  if ('identity' in requestContext && requestContext.identity?.sourceIp) {
+    address = requestContext.identity.sourceIp
+  }
+  // API Gateway v2 - has http object
+  else if ('http' in requestContext && requestContext.http?.sourceIp) {
+    address = requestContext.http.sourceIp
+  }
+  // ALB - use X-Forwarded-For header
+  else {
+    const xff = c.req.header('x-forwarded-for')
+    if (xff) {
+      const ips = xff.split(',')
+      // ALB appends the real client IP to the end of the header
+      address = ips[ips.length - 1].trim()
+    }
+  }
+
+  return {
+    remote: {
+      address,
+    },
+  }
+}