@orkestrel/middleware 0.0.1 → 0.0.3

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { isBoolean, isFiniteNumber, isFunction, isRecord, isString } from "@orkestrel/contract";
+import { integerShape, isBoolean, isFiniteNumber, isFunction, isRecord, isString, jsonShape, stringShape } from "@orkestrel/contract";
 import { HTTPError, clearCookie, clientRateKey, computeBodyETag, isCompressibleType, isHTTPError, isValidRequestId, matchesETag, mergeVary, negotiateEncoding, readSignedCookie, resolveOrigin, resolveSecure, resolveSecurityHeader, signToken, verifyToken, writeSignedCookie } from "@orkestrel/server";
 import { linkSignal } from "@orkestrel/abort";
 import { createBudget } from "@orkestrel/budget";
@@ -82,6 +82,32 @@ var DEFAULT_CSRF_SAFE_METHODS = Object.freeze([
 	"OPTIONS"
 ]);
 //#endregion
+//#region src/core/Session.ts
+/**
+* A server-managed session's default entity — the `create` option's default
+* value factory for `createSession` (ruling G: `Session` ships WITHOUT a
+* `createSession` factory of its own, since that name belongs to the
+* battery).
+*
+* @remarks
+* `data` is a live, mutable `Map` a handler reads/writes directly;
+* `createSession` persists it to the configured store on the way out.
+*
+* @example
+* ```ts
+* const session = new Session('abc123')
+* session.data.set('userId', 'u_1')
+* ```
+*/
+var Session = class {
+	id;
+	data;
+	constructor(id) {
+		this.id = id;
+		this.data = /* @__PURE__ */ new Map();
+	}
+};
+//#endregion
 //#region src/core/helpers.ts
 /**
 * Derive `createLimiter`'s default rate-limit bucket key from a request's
@@ -443,7 +469,10 @@ function transferSessionData(from, to) {
 }
 /**
 * Determine whether a value implements {@link SessionInterface} — a total
-* structural guard (§14): an `id` string plus a `data` `Map`.
+* structural guard (§14): an `id` string plus a `data` `Map`. Prototype-agnostic
+* — accepts a plain object, a null-prototype object, AND a class instance
+* (a real `Session`), since a restored/stored session is routinely a class
+* instance, not a literal.
 *
 * @param value - The candidate value
 * @returns `true` when `value` is shaped like a {@link SessionInterface}
@@ -451,11 +480,14 @@ function transferSessionData(from, to) {
 * @example
 * ```ts
 * isSession({ id: 'a', data: new Map() }) // true
+* isSession(new Session('a')) // true
 * ```
 */
 function isSession(value) {
-	if (!isRecord(value)) return false;
-	return isString(value.id) && value.data instanceof Map;
+	if (typeof value !== "object" || value === null) return false;
+	const id = Reflect.get(value, "id");
+	const data = Reflect.get(value, "data");
+	return isString(id) && data instanceof Map;
 }
 /**
 * Determine whether a value implements {@link SessionControlInterface} — a
@@ -565,34 +597,74 @@ function equalsConstantTime(a, b) {
 	for (let index = 0; index < a.length; index += 1) diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
 	return diff === 0;
 }
-//#endregion
-//#region src/core/Session.ts
 /**
-* A server-managed session's default entity — the `create` option's default
-* value factory for `createSession` (ruling G: `Session` ships WITHOUT a
-* `createSession` factory of its own, since that name belongs to the
-* battery).
+* Whether a session has aged past its idle timeout or absolute lifetime as
+* of `now` — the pure expiry predicate `MemorySessionStore` delegates to.
+*
+* @param cursors - The session's `lastSeen` (idle) and `createdAt` (absolute) instants
+* @param now - The current instant (same clock unit as `cursors`)
+* @param limits - The optional `ttl` (idle) and `lifetime` (absolute) thresholds
+* @returns `true` when either configured threshold has elapsed
+*
+* @example
+* ```ts
+* sessionExpired({ lastSeen: 0, createdAt: 0 }, 1_000, { ttl: 500 }) // true
+* ```
+*/
+function sessionExpired(cursors, now, limits) {
+	if (limits.ttl !== void 0 && now - cursors.lastSeen >= limits.ttl) return true;
+	if (limits.lifetime !== void 0 && now - cursors.createdAt >= limits.lifetime) return true;
+	return false;
+}
+/**
+* Snapshot a session's `data` Map into a plain, serializable record — the
+* projection a durable store's `set` writes to disk.
+*
+* @param session - The session to snapshot
+* @returns A plain-object copy of `session.data`, keyed alongside `session.id`
 *
 * @remarks
-* `data` is a live, mutable `Map` a handler reads/writes directly;
-* `createSession` persists it to the configured store on the way out.
+* `data` is built on a null-prototype object (`Object.create(null)`), never
+* a `{}` literal — a session key literally named `__proto__` must round-trip
+* as an OWN enumerable property instead of hitting `Object.prototype`'s
+* `__proto__` accessor (which would silently drop the entry and risk
+* polluting the shared prototype).
 *
 * @example
 * ```ts
-* const session = new Session('abc123')
-* session.data.set('userId', 'u_1')
+* snapshotSession(session) // { id: 'abc', data: { userId: 'u_1' } }
 * ```
 */
-var Session = class {
-	id;
-	data;
-	constructor(id) {
-		this.id = id;
-		this.data = /* @__PURE__ */ new Map();
-	}
-};
+function snapshotSession(session) {
+	const data = Object.create(null);
+	for (const [key, value] of session.data) data[key] = value;
+	return {
+		id: session.id,
+		data
+	};
+}
+/**
+* Rebuild a `Session` from an untrusted snapshot value (the inverse of
+* {@link snapshotSession}) — a durable store's `get` deserialization step.
+*
+* @param value - The candidate snapshot, of unknown shape
+* @returns A rebuilt `Session`, or `undefined` when `value` is malformed
+*
+* @example
+* ```ts
+* restoreSession({ id: 'abc', data: { userId: 'u_1' } }) // Session { id: 'abc', data: Map }
+* restoreSession({ id: 1 }) // undefined
+* ```
+*/
+function restoreSession(value) {
+	if (!isRecord(value)) return void 0;
+	if (!isString(value.id) || !isRecord(value.data)) return void 0;
+	const session = new Session(value.id);
+	for (const [key, entry] of Object.entries(value.data)) session.data.set(key, entry);
+	return session;
+}
 //#endregion
-//#region src/core/MemorySessionStore.ts
+//#region src/core/stores/MemorySessionStore.ts
 /**
 * The default in-process {@link SessionStoreInterface} — a `Map`-backed store
 * enforcing both an idle timeout and an absolute lifetime, with lazy
@@ -668,9 +740,10 @@ var MemorySessionStore = class {
 		this.#entries.delete(id);
 	}
 	#expired(entry, now) {
-		if (this.#ttl !== void 0 && now - entry.lastSeen >= this.#ttl) return true;
-		if (this.#lifetime !== void 0 && now - entry.createdAt >= this.#lifetime) return true;
-		return false;
+		return sessionExpired(entry, now, {
+			ttl: this.#ttl,
+			lifetime: this.#lifetime
+		});
 	}
 	#reserve(now) {
 		if (this.#entries.size < this.#capacity) return;
@@ -694,6 +767,79 @@ var MemorySessionStore = class {
 	}
 };
 //#endregion
+//#region src/core/stores/DatabaseSessionStore.ts
+/**
+* A durable {@link SessionStoreInterface} over an `@orkestrel/database`
+* table — the same idle-timeout + absolute-lifetime contract as
+* {@link MemorySessionStore}, backed by a caller-supplied `TableInterface`
+* instead of an in-process `Map`.
+*
+* @typeParam S - The session data payload type
+*
+* @remarks
+* `get` reads the row, evicts (removes the row) once `sessionExpired`
+* reports either threshold elapsed, then rebuilds the session via
+* {@link restoreSession} — a malformed snapshot or one that fails the
+* caller's `is` guard resolves `undefined` rather than throwing. A live read
+* touches `lastSeen`. `set` preserves an existing row's `createdAt` across a
+* re-`set` of the same id (stamped once at the first `set`), mirroring
+* {@link MemorySessionStore}. `delete` of an absent id is a no-op (the
+* table's `remove` contract).
+*
+* A malformed-snapshot or failed-guard `undefined` LEAVES the row in place —
+* unlike the expired path, which removes it. This is deliberate: a
+* caller-contextual `is` guard may reject a session that is still perfectly
+* valid for another flow reading the same table (a differently-shaped `S`,
+* a stricter guard mid-rollout), so `get` never destroys data on a guard
+* miss. A row that no caller's guard ever accepts again self-heals once its
+* `ttl`/`lifetime` elapses on a later `get`.
+*
+* @example
+* ```ts
+* const store = new DatabaseSessionStore(table, isSession, { ttl: 60_000 })
+* await store.set('abc', new Session('abc'), Date.now())
+* ```
+*/
+var DatabaseSessionStore = class {
+	#table;
+	#is;
+	#ttl;
+	#lifetime;
+	constructor(table, is, options) {
+		this.#table = table;
+		this.#is = is;
+		this.#ttl = options?.ttl;
+		this.#lifetime = options?.lifetime;
+	}
+	async get(id, now) {
+		const row = await this.#table.get(id);
+		if (row === void 0) return void 0;
+		if (sessionExpired(row, now, {
+			ttl: this.#ttl,
+			lifetime: this.#lifetime
+		})) {
+			await this.#table.remove(id);
+			return;
+		}
+		const session = restoreSession(row.session);
+		if (session === void 0 || !this.#is(session)) return void 0;
+		await this.#table.update(id, { lastSeen: now });
+		return session;
+	}
+	async set(id, session, now) {
+		const createdAt = (await this.#table.get(id))?.createdAt ?? now;
+		await this.#table.set({
+			id,
+			session: snapshotSession(session),
+			lastSeen: now,
+			createdAt
+		});
+	}
+	async delete(id) {
+		await this.#table.remove(id);
+	}
+};
+//#endregion
 //#region src/core/middlewares.ts
 /**
 * The outermost error-rendering battery — catches a downstream throw and
@@ -1136,9 +1282,10 @@ function createLimiter(options) {
 }
 /**
 * The body-driving battery — eagerly awaits the cached `context.body()` so
-* its throws (or a malformed-JSON `undefined`) surface before the handler runs.
+* its throws (or a malformed-JSON `undefined`) surface before the handler
+* runs, and stashes the resolved value onto {@link BodyState.body}.
 *
-* @typeParam TState - The consumer's opaque per-request state type
+* @typeParam TState - The consumer's opaque per-request state type, must carry {@link BodyState}
 * @returns A `MiddlewareHandler<TState>`
 * @throws {HTTPError} `400` when the request declares `application/json` and the body resolves `undefined`
 *
@@ -1146,7 +1293,9 @@ function createLimiter(options) {
 * The shipped `MiddlewareContext.body()` is a parameterless, server-owned
 * cache (`ServerOptions.limit` governs its size cap) — this battery carries
 * no `limit`/`decompression` options (a deliberate break from the deleted old
-* `createBodyParser` surface, which configured them itself).
+* `createBodyParser` surface, which configured them itself). `state.body` is
+* stashed from the SAME awaited call the 400 check reads — `context.body()`
+* is never invoked twice.
 *
 * @example
 * ```ts
@@ -1156,6 +1305,7 @@ function createLimiter(options) {
 function createBody() {
 	return async (request, context, next) => {
 		const body = await context.body();
+		context.state.body = body;
 		const contentType = request.headers.get("content-type");
 		if (contentType !== null && contentType.toLowerCase().startsWith("application/json") && body === void 0) throw new HTTPError(400, "invalid json");
 		return next();
@@ -1306,6 +1456,48 @@ function createCSRF(options) {
 		return next();
 	};
 }
+/**
+* Scope a battery to run ONLY on a set of exact pathnames — elsewhere it
+* steps aside via `next()`.
+*
+* @typeParam TState - The consumer's opaque per-request state type
+* @param paths - One pathname, or a set of pathnames, matched exactly against `context.url.pathname`
+* @param handler - The battery to run when `paths` matches
+* @returns A `MiddlewareHandler<TState>`
+*
+* @example
+* ```ts
+* const scoped = only('/admin', createBearer({ secret }))
+* ```
+*/
+function only(paths, handler) {
+	const matches = new Set(typeof paths === "string" ? [paths] : paths);
+	return async (request, context, next) => {
+		if (matches.has(context.url.pathname)) return handler(request, context, next);
+		return next();
+	};
+}
+/**
+* Scope a battery to run everywhere EXCEPT a set of exact pathnames — there
+* it steps aside via `next()`.
+*
+* @typeParam TState - The consumer's opaque per-request state type
+* @param paths - One pathname, or a set of pathnames, matched exactly against `context.url.pathname`
+* @param handler - The battery to run when `paths` does not match
+* @returns A `MiddlewareHandler<TState>`
+*
+* @example
+* ```ts
+* const scoped = except('/health', createTelemetry({ record }))
+* ```
+*/
+function except(paths, handler) {
+	const matches = new Set(typeof paths === "string" ? [paths] : paths);
+	return async (request, context, next) => {
+		if (matches.has(context.url.pathname)) return next();
+		return handler(request, context, next);
+	};
+}
 //#endregion
 //#region src/core/factories.ts
 /**
@@ -1393,7 +1585,55 @@ function createHeaderTransport(options) {
 function createMemorySessionStore(options) {
 	return new MemorySessionStore(options);
 }
+/**
+* The `@orkestrel/database` column shape for a {@link SessionRow} table — pass
+* as-is to `createDatabase({ tables: { sessions: sessionColumns } })` so an
+* app declaring a durable session table never hand-writes the shape.
+*
+* @remarks
+* `lastSeen`/`createdAt` are `integerShape({ min: 0 })` — the table VALIDATES
+* them as integers, so `DatabaseSessionStore`'s `now` clock must yield
+* integer milliseconds (`Date.now()`, the implicit default `createSession`
+* clock). A fractional clock (`performance.now()`) fails the write with a
+* validation error; `MemorySessionStore` carries no such column shape and
+* accepts a fractional clock without complaint.
+*
+* @example
+* ```ts
+* const db = createDatabase({ driver, tables: { sessions: sessionColumns } })
+* ```
+*/
+var sessionColumns = {
+	id: stringShape(),
+	session: jsonShape(),
+	lastSeen: integerShape({ min: 0 }),
+	createdAt: integerShape({ min: 0 })
+};
+/**
+* Create a {@link DatabaseSessionStore} as a {@link SessionStoreInterface} —
+* the durable counterpart to `createMemorySessionStore`, over a caller-opened
+* `@orkestrel/database` table (declare it with {@link sessionColumns}).
+*
+* @typeParam S - The session data payload type
+* @param table - The backing `TableInterface<SessionRow>`
+* @param is - A {@link Guard} narrowing a restored snapshot to `S`
+* @param options - The idle `ttl` / absolute `lifetime` thresholds
+* @returns A {@link SessionStoreInterface}
+*
+* @remarks
+* This factory only wraps `new DatabaseSessionStore(...)` — it never opens a
+* database or driver itself; the caller owns that lifecycle and passes in an
+* already-open table.
+*
+* @example
+* ```ts
+* const store = createDatabaseSessionStore(db.table('sessions'), isSession, { ttl: 60_000 })
+* ```
+*/
+function createDatabaseSessionStore(table, is, options) {
+	return new DatabaseSessionStore(table, is, options);
+}
 //#endregion
-export { DEFAULT_BEARER_HEADER, DEFAULT_BEARER_SCHEME, DEFAULT_CLUSTER, DEFAULT_COEP, DEFAULT_COMPRESSION_ENCODINGS, DEFAULT_COMPRESSION_THRESHOLD, DEFAULT_COOP, DEFAULT_CORP, DEFAULT_CORS_HEADERS, DEFAULT_CORS_METHODS, DEFAULT_CSP, DEFAULT_CSRF_COOKIE, DEFAULT_CSRF_FIELD, DEFAULT_CSRF_HEADER, DEFAULT_CSRF_SAFE_METHODS, DEFAULT_DEADLINE_STATUS, DEFAULT_FRAME_OPTIONS, DEFAULT_HSTS, DEFAULT_IDENTIFIER_HEADER, DEFAULT_LIMITER_CAPACITY, DEFAULT_LIMITER_MESSAGE, DEFAULT_PERMISSIONS_POLICY, DEFAULT_REFERRER_POLICY, DEFAULT_SESSION_CAPACITY, DEFAULT_SESSION_COOKIE, DEFAULT_SESSION_HEADER, MemorySessionStore, Session, buildClientInfo, buildRateLimitField, buildRateLimitPolicyField, buildRetryAfter, compressResponse, createBearer, createBody, createBoundary, createCSRF, createCompression, createCookieTransport, createCors, createDeadline, createETag, createForwarded, createHeaderTransport, createLimiter, createMemorySessionStore, createSecurity, createSession, createTelemetry, detectEncodings, equalsConstantTime, isBufferingIneligible, isCompressionNegotiated, isMultipartBody, isMultipartFile, isPreflight, isSession, isSessionControl, matchesTrustedEntry, rebuildResponse, resolveForwardedFor, resolveKey, resolveOptInHeader, transferSessionData };
+export { DEFAULT_BEARER_HEADER, DEFAULT_BEARER_SCHEME, DEFAULT_CLUSTER, DEFAULT_COEP, DEFAULT_COMPRESSION_ENCODINGS, DEFAULT_COMPRESSION_THRESHOLD, DEFAULT_COOP, DEFAULT_CORP, DEFAULT_CORS_HEADERS, DEFAULT_CORS_METHODS, DEFAULT_CSP, DEFAULT_CSRF_COOKIE, DEFAULT_CSRF_FIELD, DEFAULT_CSRF_HEADER, DEFAULT_CSRF_SAFE_METHODS, DEFAULT_DEADLINE_STATUS, DEFAULT_FRAME_OPTIONS, DEFAULT_HSTS, DEFAULT_IDENTIFIER_HEADER, DEFAULT_LIMITER_CAPACITY, DEFAULT_LIMITER_MESSAGE, DEFAULT_PERMISSIONS_POLICY, DEFAULT_REFERRER_POLICY, DEFAULT_SESSION_CAPACITY, DEFAULT_SESSION_COOKIE, DEFAULT_SESSION_HEADER, DatabaseSessionStore, MemorySessionStore, Session, buildClientInfo, buildRateLimitField, buildRateLimitPolicyField, buildRetryAfter, compressResponse, createBearer, createBody, createBoundary, createCSRF, createCompression, createCookieTransport, createCors, createDatabaseSessionStore, createDeadline, createETag, createForwarded, createHeaderTransport, createLimiter, createMemorySessionStore, createSecurity, createSession, createTelemetry, detectEncodings, equalsConstantTime, except, isBufferingIneligible, isCompressionNegotiated, isMultipartBody, isMultipartFile, isPreflight, isSession, isSessionControl, matchesTrustedEntry, only, rebuildResponse, resolveForwardedFor, resolveKey, resolveOptInHeader, restoreSession, sessionColumns, sessionExpired, snapshotSession, transferSessionData };
 
 //# sourceMappingURL=index.js.map