lambder 4.3.1 → 4.4.1

package/dist/core/LambderPublicFiles.js

@@ -8,36 +8,65 @@ const DEFAULT_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
 const DEFAULT_CACHE_CONTROL = "public, max-age=3600";
 const DEFAULT_MEMORY_CACHE_MAX_BYTES = 32 * 1024 * 1024;
 const DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES = 2 * 1024 * 1024;
+/**
+ * Files from a folder on the Lambda's filesystem, typically the build output
+ * bundled into the deployment package. Reads stay under root. The default
+ * source of servePublicFiles, over publicPath.
+ */
+export class LambderLocalFileSource {
+    root;
+    constructor({ root }) {
+        this.root = root;
+    }
+    async read(relativePath) {
+        const fs = await getFS();
+        const path = await getPath();
+        if (!fs || !path)
+            throw new Error("LambderLocalFileSource requires a Node.js environment.");
+        const base = path.resolve(this.root);
+        const absolute = path.resolve(base, relativePath);
+        if (absolute !== base && !absolute.startsWith(base + path.sep))
+            return null;
+        const stat = await fs.promises.stat(absolute).catch(() => null);
+        if (!stat?.isFile())
+            return null;
+        return { body: await fs.promises.readFile(absolute) };
+    }
+}
+/** Strip the leading slash and reject traversal; null for a path that names no file (empty, or a directory). */
+const toRelativePath = (target) => {
+    if (target.split("/").some((segment) => segment === ".."))
+        return null;
+    const relative = target.startsWith("/") ? target.slice(1) : target;
+    if (relative === "" || relative.endsWith("/"))
+        return null;
+    return relative;
+};
 /**
  * Terminal public-file handler registered via lambder.servePublicFiles().
  * Runs only when no route matched, so it can never shadow routes registered
- * after it. Serves real files under publicPath (traversal-safe, mime-typed,
+ * after it. Serves files from its source (traversal-safe, mime-typed,
  * memory-cached, immutable-cache heuristic for content-hashed assets) and
- * falls through to the route fallback when the file does not exist.
+ * falls through to the route fallback when the source has no such file.
  */
 export class LambderPublicFilesHandler {
-    publicPath;
+    source;
     options;
     fileCache = new Map();
     fileCacheBytes = 0;
-    constructor(publicPath, options) {
-        this.publicPath = publicPath;
+    constructor(source, options) {
+        this.source = source;
         this.options = options;
     }
     /** Serve the mapped file, or return null to fall through. */
     async handle(ctx) {
-        const fs = await getFS();
-        const path = await getPath();
-        if (!fs || !path)
-            throw new Error("servePublicFiles requires a Node.js environment.");
         const mappedPath = this.options.path ? this.options.path(ctx) : ctx.path;
         if (!mappedPath)
             return null;
-        const publicRoot = path.resolve(this.publicPath);
-        const filePath = this.resolveSafe(path, publicRoot, mappedPath);
-        if (!filePath)
+        const relativePath = toRelativePath(mappedPath);
+        if (relativePath === null)
             return null;
-        const file = await this.readFileCached(fs, filePath);
+        const file = await this.readCached(relativePath);
         if (!file)
             return null;
         const compressOption = this.options.compress;
@@ -46,61 +75,52 @@ export class LambderPublicFilesHandler {
             statusCode: 200,
             headers: {
                 "Content-Type": file.mimeType,
-                "Cache-Control": this.cacheControlFor(ctx, filePath),
+                "Cache-Control": this.cacheControlFor(ctx, relativePath),
             },
             body: file.body,
             compress,
         });
     }
-    /** Join base+target and require the result to stay under base. */
-    resolveSafe(path, base, target) {
-        if (target.split("/").some((segment) => segment === ".."))
-            return null;
-        const normalizedTarget = target.startsWith("/") ? target.slice(1) : target;
-        const absolute = path.resolve(base, normalizedTarget);
-        if (absolute !== base && !absolute.startsWith(base + path.sep))
-            return null;
-        return absolute;
-    }
-    /** Read a file, caching small files in memory for warm invocations. */
-    async readFileCached(fs, filePath) {
-        const cached = this.fileCache.get(filePath);
+    /** Read from the source, caching small files in memory for warm invocations. */
+    async readCached(relativePath) {
+        const cached = this.fileCache.get(relativePath);
         if (cached)
             return cached;
-        const stat = await fs.promises.stat(filePath).catch(() => null);
-        if (!stat?.isFile())
+        const file = await this.source.read(relativePath);
+        if (!file)
             return null;
-        const body = await fs.promises.readFile(filePath);
-        const mimeType = mimeTypeResolver.lookup(filePath) || "application/octet-stream";
-        const entry = { body, mimeType };
+        const entry = {
+            body: file.body,
+            mimeType: file.mimeType || mimeTypeResolver.lookup(relativePath) || "application/octet-stream",
+        };
         const cacheConfig = this.options.memoryCache;
         if (cacheConfig !== false) {
             const maxBytes = cacheConfig?.maxBytes ?? DEFAULT_MEMORY_CACHE_MAX_BYTES;
             const maxFileBytes = cacheConfig?.maxFileBytes ?? DEFAULT_MEMORY_CACHE_MAX_FILE_BYTES;
-            if (body.length <= maxFileBytes) {
+            if (entry.body.length <= maxFileBytes) {
                 // Evict oldest entries until the new file fits the budget.
                 for (const [key, value] of this.fileCache) {
-                    if (this.fileCacheBytes + body.length <= maxBytes)
+                    if (this.fileCacheBytes + entry.body.length <= maxBytes)
                         break;
                     this.fileCache.delete(key);
                     this.fileCacheBytes -= value.body.length;
                 }
-                if (this.fileCacheBytes + body.length <= maxBytes) {
-                    this.fileCache.set(filePath, entry);
-                    this.fileCacheBytes += body.length;
+                if (this.fileCacheBytes + entry.body.length <= maxBytes) {
+                    this.fileCache.set(relativePath, entry);
+                    this.fileCacheBytes += entry.body.length;
                 }
             }
         }
         return entry;
     }
-    cacheControlFor(ctx, filePath) {
+    cacheControlFor(ctx, relativePath) {
         const cacheOption = this.options.cacheControl;
         if (typeof cacheOption === "function")
-            return cacheOption(ctx, filePath);
+            return cacheOption(ctx, relativePath);
         const immutablePattern = this.options.immutablePattern === false
             ? null
             : (this.options.immutablePattern ?? DEFAULT_IMMUTABLE_PATTERN);
-        if (immutablePattern && immutablePattern.test(filePath)) {
+        if (immutablePattern && immutablePattern.test(relativePath)) {
             return this.options.immutableCacheControl ?? DEFAULT_IMMUTABLE_CACHE_CONTROL;
         }
         return cacheOption ?? DEFAULT_CACHE_CONTROL;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import Lambder from './core/Lambder.js';
 export default Lambder;
 export { initLambder } from './core/Lambder.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
-export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderIdempotencyKeyScope } from "./client/LambderCaller.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope } from "./client/LambderCaller.js";
 export { LambderApiError, isLambderApiError, refuse, LAMBDER_REFUSAL_CODES } from "./shared/LambderApiError.js";
 export type { LambderApiErrorOptions, LambderRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/LambderApiError.js";
 export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
@@ -15,10 +15,13 @@ export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 export type { LambderTemplateData, LambderTemplatingEngineOptions } from "./core/LambderTemplatingEngine.js";
 export type { LambderResponseOptions, LambderRawResponseInit, } from "./core/LambderResponseBuilder.js";
 export type { LambderRouteMatcher, LambderCorsConfig, LambderCreateOptions, LambderSessionOptions, ConditionFunction, RouteCondition, PathParamsOf, LambderActionTools, LambderHandler, LambderIndexHtmlOptions, } from "./core/Lambder.js";
-export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
-export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
+export { LambderPublicFilesHandler, LambderLocalFileSource } from "./core/LambderPublicFiles.js";
+export type { LambderPublicFilesOptions, LambderPublicFileSource, LambderPublicFile } from "./core/LambderPublicFiles.js";
+export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
+export type { LambderS3FileSourceOptions } from "./stores/LambderS3FileSource.js";
 export type { LambderSessionCookieOptions } from "./session/LambderSessionController.js";
-export type { LambderSessionContext, LambderCreatedSession, LambderSessionDataRefreshConfig, LambderSessionCompressionConfig } from "./session/LambderSessionManager.js";
+export type { LambderSessionContext, LambderCreatedSession, LambderSessionDataRefreshConfig } from "./session/LambderSessionManager.js";
+export type { LambderCompressionOption, LambderCompressionConfig } from "./stores/LambderDdbCompression.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";
 export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./stores/LambderDdbCache.js";

package/dist/index.js

@@ -15,7 +15,8 @@ export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtm
 // Comment-based HTML templating engine (build-pipeline-safe slots and conditionals, standalone)
 export { LambderTemplatingEngine } from "./core/LambderTemplatingEngine.js";
 // Public file serving
-export { LambderPublicFilesHandler } from "./core/LambderPublicFiles.js";
+export { LambderPublicFilesHandler, LambderLocalFileSource } from "./core/LambderPublicFiles.js";
+export { LambderS3FileSource } from "./stores/LambderS3FileSource.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 // DynamoDB-backed compressed cache (standalone, server-only)
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";

package/dist/session/LambderSessionController.d.ts

@@ -49,6 +49,13 @@ export default class LambderSessionController<TSessionData = any> {
      * session and touches no cookies, so it works on any subject.
      */
     deleteSessionAllByKey(sessionKey: string): Promise<void>;
+    /**
+     * Marks the data of every session of the given sessionKey stale, so each
+     * renews via dataRefresh on its next read: the way to apply a change to
+     * a subject's roles or permissions immediately, without logging them
+     * out. Needs no fetched session; requires dataRefresh.
+     */
+    expireSessionDataAllByKey(sessionKey: string): Promise<void>;
     endSession(): Promise<void>;
     endSessionAll(): Promise<void>;
 }

package/dist/session/LambderSessionController.js

@@ -151,6 +151,16 @@ export default class LambderSessionController {
         await this.lambderSessionManager.deleteSessionAllByKey(sessionKey);
     }
     ;
+    /**
+     * Marks the data of every session of the given sessionKey stale, so each
+     * renews via dataRefresh on its next read: the way to apply a change to
+     * a subject's roles or permissions immediately, without logging them
+     * out. Needs no fetched session; requires dataRefresh.
+     */
+    async expireSessionDataAllByKey(sessionKey) {
+        await this.lambderSessionManager.expireSessionDataAllByKey(sessionKey);
+    }
+    ;
     async endSession() {
         if (!this.ctx.session)
             throw new Error("Session not found.");

package/dist/session/LambderSessionManager.d.ts

@@ -1,3 +1,4 @@
+import { type LambderCompressionOption } from "../stores/LambderDdbCompression.js";
 export type LambderSessionContext<SessionData = any> = {
     [x: string]: any;
     /**
@@ -53,23 +54,6 @@ export type LambderSessionDataRefreshConfig<SessionData = any> = {
      */
     refresh: (session: LambderSessionContext<SessionData>) => Promise<SessionData | null>;
 };
-/**
- * Brotli compression of session.data at rest. The option is `true` by
- * default, which equals `{ minBytes: 0 }`: every record compressed. A
- * compressed record carries the data's JSON as Brotli bytes (`dataBr`)
- * beside its byte length (`dataBytes`), the scheme LambderDdbCache and
- * LambderDdbIdempotency use. Below minBytes, or with compression off, the
- * record keeps a plain `data` attribute. Reads accept both shapes, so the
- * setting can be switched on or off on a live table: records written under
- * the other setting keep reading, and each is rewritten in the current
- * shape on its next write.
- */
-export type LambderSessionCompressionConfig = {
-    /** JSON byte length from which data is stored compressed. Default: 0 (always). */
-    minBytes?: number;
-    /** Brotli quality (0-11), like LambderDdbCache. Default: 5. */
-    quality?: number;
-};
 /**
  * Wraps errors thrown by the dataRefresh callback so they stay
  * distinguishable from "no session": fetchSessionIfExists() swallows missing
@@ -108,7 +92,7 @@ export default class LambderSessionManager {
         enableSlidingExpiration?: boolean;
         slidingWriteIntervalSeconds?: number;
         dataRefresh?: LambderSessionDataRefreshConfig;
-        compression?: boolean | LambderSessionCompressionConfig;
+        compression?: LambderCompressionOption;
     });
     private sessionUserKeyHasher;
     /**
@@ -124,10 +108,10 @@ export default class LambderSessionManager {
      * Persists a session record. With compression on, `data` is stored as
      * Brotli bytes (`dataBr`) beside its JSON byte length (`dataBytes`)
      * once the JSON reaches minBytes; otherwise it stays a plain attribute.
-     * See LambderSessionCompressionConfig.
      */
     private ddbPutItem;
     private ddbDeleteItem;
+    /** Sort keys of every session under a partition (the callers only need the keys). */
     private ddbQueryAllByPartitionKey;
     private ddbDeleteAllByPartitionKey;
     createSession(sessionKey: string, data?: any, ttlInSeconds?: number, options?: {
@@ -152,5 +136,15 @@ export default class LambderSessionManager {
      * session record.
      */
     deleteSessionAllByKey(sessionKey: string): Promise<boolean>;
+    /**
+     * Marks the data of every session of the given sessionKey stale, so each
+     * renews via dataRefresh on its next read: "this subject's roles or
+     * permissions changed, apply it now", without logging the subject out
+     * (deleteSessionAllByKey) and without waiting for the data TTL. Stamps
+     * dataExpiresAt only, conditionally on the record still existing, so it
+     * neither resurrects a session deleted in between nor overwrites a
+     * concurrent write. Requires dataRefresh to be configured.
+     */
+    expireSessionDataAllByKey(sessionKey: string): Promise<boolean>;
     regenerateSession(session: LambderSessionContext): Promise<LambderCreatedSession>;
 }

package/dist/session/LambderSessionManager.js

@@ -1,7 +1,16 @@
 import crypto from "crypto";
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { DynamoDBDocumentClient, QueryCommand, DeleteCommand, PutCommand, GetCommand } from "@aws-sdk/lib-dynamodb";
-import { brotliCompressText, brotliRestoreText } from "../stores/LambderDdbCompression.js";
+import { DynamoDBDocumentClient, QueryCommand, DeleteCommand, PutCommand, GetCommand, UpdateCommand } from "@aws-sdk/lib-dynamodb";
+import { brotliCompressText, brotliRestoreText, resolveCompressionOption, } from "../stores/LambderDdbCompression.js";
+/**
+ * Session compression defaults: every record compressed (see
+ * LambderCompressionOption for the option's shape and toggle semantics).
+ * A compressed record carries the data's JSON as Brotli bytes (`dataBr`)
+ * beside its byte length (`dataBytes`), the scheme LambderDdbCache and
+ * LambderDdbIdempotency use; below minBytes, or with compression off, the
+ * record keeps a plain `data` attribute.
+ */
+const SESSION_COMPRESSION_DEFAULTS = { minBytes: 0, quality: 5 };
 /**
  * Wraps errors thrown by the dataRefresh callback so they stay
  * distinguishable from "no session": fetchSessionIfExists() swallows missing
@@ -37,7 +46,7 @@ export default class LambderSessionManager {
     slidingWriteIntervalSeconds;
     dataRefresh;
     compression;
-    constructor({ tableName, tableRegion, partitionKey, sortKey, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, compression = true, }) {
+    constructor({ tableName, tableRegion, partitionKey, sortKey, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, compression, }) {
         this.tableName = tableName;
         this.sessionSalt = sessionSalt;
         this.partitionKey = partitionKey;
@@ -45,19 +54,7 @@ export default class LambderSessionManager {
         this.enableSlidingExpiration = enableSlidingExpiration;
         this.slidingWriteIntervalSeconds = slidingWriteIntervalSeconds ?? null;
         this.dataRefresh = dataRefresh ?? null;
-        const compressionConfig = compression === true ? {} : compression;
-        this.compression = compressionConfig ? {
-            minBytes: compressionConfig.minBytes ?? 0,
-            quality: compressionConfig.quality ?? 5,
-        } : null;
-        if (this.compression) {
-            if (!Number.isSafeInteger(this.compression.minBytes) || this.compression.minBytes < 0) {
-                throw new Error("compression.minBytes must be a non-negative integer");
-            }
-            if (!Number.isInteger(this.compression.quality) || this.compression.quality < 0 || this.compression.quality > 11) {
-                throw new Error("compression.quality must be an integer from 0 to 11");
-            }
-        }
+        this.compression = resolveCompressionOption(compression, SESSION_COMPRESSION_DEFAULTS);
         const ddbClient = new DynamoDBClient({ region: tableRegion });
         this.ddbDocumentClient = DynamoDBDocumentClient.from(ddbClient);
     }
@@ -93,7 +90,6 @@ export default class LambderSessionManager {
      * Persists a session record. With compression on, `data` is stored as
      * Brotli bytes (`dataBr`) beside its JSON byte length (`dataBytes`)
      * once the JSON reaches minBytes; otherwise it stays a plain attribute.
-     * See LambderSessionCompressionConfig.
      */
     async ddbPutItem(session) {
         const { data, ...item } = session;
@@ -112,11 +108,13 @@ export default class LambderSessionManager {
         return await this.ddbDocumentClient.send(new DeleteCommand({ TableName: this.tableName, Key: key, }));
     }
     ;
+    /** Sort keys of every session under a partition (the callers only need the keys). */
     async ddbQueryAllByPartitionKey(partitionValue) {
         const params = {
             TableName: this.tableName,
             KeyConditionExpression: "#pk = :pv",
-            ExpressionAttributeNames: { "#pk": this.partitionKey },
+            ProjectionExpression: "#sk",
+            ExpressionAttributeNames: { "#pk": this.partitionKey, "#sk": this.sortKey },
             ExpressionAttributeValues: { ":pv": partitionValue },
         };
         const queryResults = [];
@@ -345,6 +343,40 @@ export default class LambderSessionManager {
         return true;
     }
     ;
+    /**
+     * Marks the data of every session of the given sessionKey stale, so each
+     * renews via dataRefresh on its next read: "this subject's roles or
+     * permissions changed, apply it now", without logging the subject out
+     * (deleteSessionAllByKey) and without waiting for the data TTL. Stamps
+     * dataExpiresAt only, conditionally on the record still existing, so it
+     * neither resurrects a session deleted in between nor overwrites a
+     * concurrent write. Requires dataRefresh to be configured.
+     */
+    async expireSessionDataAllByKey(sessionKey) {
+        if (!this.dataRefresh)
+            throw new Error("dataRefresh is not configured. Pass session.dataRefresh at creation to enable.");
+        const partitionValue = this.sessionUserKeyHasher(sessionKey);
+        const now = Math.floor(Date.now() / 1000);
+        for (const item of await this.ddbQueryAllByPartitionKey(partitionValue)) {
+            try {
+                await this.ddbDocumentClient.send(new UpdateCommand({
+                    TableName: this.tableName,
+                    Key: { [this.partitionKey]: partitionValue, [this.sortKey]: item[this.sortKey] },
+                    UpdateExpression: "SET #dataExpiresAt = :now",
+                    ConditionExpression: "attribute_exists(#sk)",
+                    ExpressionAttributeNames: { "#dataExpiresAt": "dataExpiresAt", "#sk": this.sortKey },
+                    ExpressionAttributeValues: { ":now": now },
+                }));
+            }
+            catch (err) {
+                // Deleted between the query and the update: nothing left to expire.
+                if (err.name !== "ConditionalCheckFailedException")
+                    throw err;
+            }
+        }
+        return true;
+    }
+    ;
     async regenerateSession(session) {
         if (!session)
             throw new Error("Invalid session");

package/dist/stores/LambderDdbCache.d.ts

@@ -1,4 +1,5 @@
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { type LambderCompressionOption } from "./LambderDdbCompression.js";
 export interface LambderDdbCacheOptions {
     tableName: string;
     region?: string;
@@ -7,7 +8,13 @@ export interface LambderDdbCacheOptions {
     namespace?: string;
     defaultTtlSeconds?: number;
     chunkBytes?: number;
-    compressionQuality?: number;
+    /**
+     * Brotli compression of stored values. `true` (the default) is
+     * `{ minBytes: 0, quality: 5 }`: every value compressed; `false` stores
+     * values plain; an object overrides the defaults. The manifest records
+     * each value's encoding, so it can be switched on or off on a live table.
+     */
+    compression?: LambderCompressionOption;
     maxValueBytes?: number;
     memoryMaxBytes?: number;
     client?: DynamoDBClient;
@@ -22,8 +29,10 @@ export interface LambderDdbCacheGetOrSetOptions extends LambderDdbCacheSetOption
 /**
  * Persistent JSON cache backed by DynamoDB.
  *
- * Values are Brotli-compressed. Values within the safe DynamoDB item budget are
- * stored directly in the manifest for a single-request read; larger values are
+ * Values are Brotli-compressed by default (`compression` option; the manifest
+ * records each value's encoding, so the option can be switched on a live
+ * table). Values within the safe DynamoDB item budget are stored directly in
+ * the manifest for a single-request read; larger values are
  * split into versioned binary chunks. A manifest is written only after every
  * chunk succeeds, so readers see either the previous complete version or the
  * new complete version. DynamoDB TTL is cleanup only; every read also checks
@@ -41,7 +50,7 @@ export declare class LambderDdbCache {
     private readonly client;
     private readonly defaultTtlSeconds;
     private readonly chunkBytes;
-    private readonly compressionQuality;
+    private readonly compression;
     private readonly maxValueBytes;
     private readonly memory;
     private readonly inFlight;
@@ -64,6 +73,8 @@ export declare class LambderDdbCache {
     private readChunks;
     private invalidateManifest;
     private batchWrite;
+    /** The JSON text of a stored payload. */
+    private decode;
     private remember;
     private normalizeKey;
     private partitionKey;