blogwright-analytics 0.3.3

package/dist/aws/lambda.js

@@ -0,0 +1,339 @@
+import { AwsError } from 'blogwright-core';
+import { rethrowWithContext } from './errors.js';
+/**
+ * AWS Lambda control-plane client for the *standard* function API - create, get,
+ * update (code and configuration) and delete for the one function this plugin owns,
+ * the record-transform Lambda that Firehose runs over every CloudFront log record.
+ *
+ * **Its relationship to core's `MicrovmsClient`
+ * (`packages/core/src/aws/microvms.ts`).** The two clients share a host and a SigV4
+ * signing name, and share nothing else. Both resolve to
+ * `lambda.<region>.amazonaws.com` and both sign as `lambda` - Lambda MicroVMs is
+ * served off the standard Lambda endpoint - and what separates them is the path
+ * prefix. `MicrovmsClient` owns `/2025-09-09/` (`microvm-images`, `microvms`,
+ * `auth-token`) and owns it exclusively: not one request this module issues carries
+ * that prefix, which `lambda.test.ts` asserts over every recorded URL of every
+ * operation. This module owns `/2015-03-31/functions`, the function API that has
+ * been Lambda's since 2015. Neither module's `PATHS` table can collide with the
+ * other's, and neither needs to know the other exists at runtime.
+ *
+ * It lives in `blogwright-analytics`, not in core: core's `SIGNING_NAMES` gains no
+ * `lambda` key (`microvms` is already keyed there and maps to the `lambda` signing
+ * name), and every request here signs through the `{ service: 'lambda', signingName:
+ * 'lambda' }` descriptor the plugin transport seam accepts (see
+ * `packages/core/src/aws/endpoint.ts`'s `ServiceDescriptor`), which resolves to the
+ * canonical `lambda.<region>.amazonaws.com` host through `canonicalHost`'s default
+ * `${service}.${region}.amazonaws.com` branch.
+ *
+ * Protocol: REST-JSON - a method and a path per operation with
+ * `content-type: application/json`, the shape `packages/core/src/aws/microvms.ts`
+ * and `s3tables.ts` next door use, not the AWS-JSON `POST /` + `x-amz-target` of the
+ * `firehose.ts` and `glue.ts` siblings. Methods and paths below are verified
+ * operation by operation against the Lambda API reference; two of them are easy to
+ * get wrong and are pinned by their own tests:
+ *
+ * - The deployment package is nested as `Code.ZipFile` in `CreateFunction`'s body
+ *   but is a **top-level** `ZipFile` in `UpdateFunctionCode`'s. The two operations
+ *   do not share a body shape, and a create-shaped body sent to `/code` would set no
+ *   code at all.
+ * - `GetFunction`'s response nests the function's configuration under
+ *   `Configuration` (beside `Code`, `Tags` and `Concurrency`), while
+ *   `CreateFunction`, `UpdateFunctionCode` and `UpdateFunctionConfiguration` return a
+ *   `FunctionConfiguration` at the top level. Reading `FunctionArn` off the root of a
+ *   `GetFunction` response yields `undefined`, not an error.
+ *
+ * `Qualifier` is deliberately never sent, so every operation addresses the
+ * unpublished `$LATEST` version. Nothing in this pipeline publishes a version or an
+ * alias, and `Publish` is likewise never sent: a published version would freeze code
+ * and configuration that the transform-function node reconciles in place.
+ *
+ * **Error regime (rest-json, header-only exception names).** This service is in the
+ * same regime as the `s3tables.ts` sibling and not the `firehose.ts`/`glue.ts` ones.
+ * Lambda puts the exception name in an `x-amzn-ErrorType` header and its request id
+ * in `x-amzn-RequestId`, and its error *body* carries at most `{"Type": ...,
+ * "message": ...}` - where `Type` is the category, `"User"` or `"Service"`, never the
+ * exception name, and is absent altogether on the unmodelled failures. Core's `parseError` (`packages/core/src/aws/signer.ts`) reads a code from the
+ * body alone (`__type`/`code`/`Code`), so for every Lambda failure `AwsError.code`
+ * arrives as `"Http<status>"` and `AwsError.requestId` is always `undefined`. Probed
+ * against the live endpoint, not read off a documentation page: an unauthenticated
+ * `GET https://lambda.us-east-1.amazonaws.com/2015-03-31/functions/<name>` answers
+ * `403` with `x-amzn-errortype: MissingAuthenticationTokenException`,
+ * `x-amzn-requestid: <uuid>` and a body of exactly
+ * `{"message":"Missing Authentication Token"}`.
+ *
+ * The status code is what survives, and unlike S3 Tables' single generic
+ * `ConflictException` the statuses here are genuinely discriminating - each of the
+ * two this client narrows on belongs to exactly one exception:
+ *
+ * | status | exception                     | meaning on this client's operations |
+ * | ------ | ----------------------------- | ----------------------------------- |
+ * | 404    | `ResourceNotFoundException`   | the function is absent - *except on create*, where it is the execution role (or a layer, or a code-signing config) that is absent |
+ * | 409    | `ResourceConflictException`   | "already exists" on create; "another operation is in progress" on update and delete |
+ * | 412    | `PreconditionFailedException` | a `RevisionId` mismatch; unreachable here, no `RevisionId` is ever sent |
+ * | 400    | `InvalidParameterValueException`, `CodeStorageExceededException`, `CodeVerificationFailedException`, `InvalidCodeSignatureException` | |
+ * | 429    | `TooManyRequestsException`    | |
+ * | 500    | `ServiceException`            | |
+ *
+ * So `AwsError.isNotFound` works on this service through its `statusCode === 404`
+ * limb (its `code` regex never matches `"Http404"`), while `isAlreadyExists` matches
+ * nothing at all and `isFunctionAlreadyExists` below bridges the gap. Both
+ * overloadings in the table above are load-bearing and are handled where they arise:
+ * see `createFunction` for the 404 one and `deleteFunction` for the 409 one.
+ *
+ * The durable fix is core-level and deliberately not made here (this task must not
+ * touch `packages/core`): `parseError` should read `x-amzn-errortype` and
+ * `x-amzn-requestid` from the headers it already receives, which would hand this
+ * client a real exception name and a request id to quote to AWS support. It is
+ * recorded as a follow-up in the plan's open questions and would subsume both this
+ * module's 409 limb and `s3tables.ts`'s.
+ *
+ * The floci emulator does not implement this service, so it is covered by transport
+ * mocks in tests.
+ */
+const SERVICE = { service: 'lambda', signingName: 'lambda' };
+/**
+ * The standard Lambda function API's date prefix. Distinct from
+ * `packages/core/src/aws/microvms.ts`'s `API = '/2025-09-09'`, which that module owns
+ * and this one never emits.
+ */
+const API = '/2015-03-31';
+const PATHS = {
+    functions: `${API}/functions`,
+    // The function name is percent-encoded into its path segment the way
+    // `microvms.ts:17` encodes an image id. Lambda's own name pattern would not need
+    // it, but the encoding is what keeps a caller-supplied name inside its segment
+    // rather than letting it address a different operation.
+    function: (name) => `${API}/functions/${encodeURIComponent(name)}`,
+    functionCode: (name) => `${API}/functions/${encodeURIComponent(name)}/code`,
+    functionConfiguration: (name) => `${API}/functions/${encodeURIComponent(name)}/configuration`,
+};
+/**
+ * The only `PackageType` this client deploys. Sent explicitly on create rather than
+ * relying on the service default, so the request states the packaging model its
+ * `Code.ZipFile` and its `Handler`/`Runtime` depend on - the same call `firehose.ts`
+ * makes for `DeliveryStreamType`.
+ */
+const PACKAGE_TYPE = 'Zip';
+function toFunctionState(state) {
+    switch (state) {
+        case 'Pending':
+            return 'pending';
+        case 'Active':
+            return 'active';
+        case 'Inactive':
+            return 'inactive';
+        case 'Failed':
+            return 'failed';
+        case 'Deactivating':
+            return 'deactivating';
+        case 'Deactivated':
+            return 'deactivated';
+        case 'ActiveNonInvocable':
+            return 'active-non-invocable';
+        case 'Deleting':
+            return 'deleting';
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * Map `GetFunction`'s response onto the domain value. A 200 is the existence signal:
+ * `Configuration` is optional in the service model, but a 200 carrying none is
+ * neither documented nor observed, so an absent field falls back rather than
+ * inventing a second "does not exist" answer next to `ResourceNotFoundException` -
+ * the same call `glue.ts`'s `normalizeCatalog` and `s3tables.ts`'s `normalizeTable`
+ * make.
+ */
+function normalizeFunction(out, fallbackName) {
+    const configuration = out.Configuration;
+    return {
+        name: configuration?.FunctionName ?? fallbackName,
+        arn: configuration?.FunctionArn ?? '',
+        state: toFunctionState(configuration?.State),
+    };
+}
+/** Encode the deployment package for the wire's blob member; the one place the base64 step is spelled out. */
+function encodeZip(zipFile) {
+    return Buffer.from(zipFile).toString('base64');
+}
+/**
+ * Build the version-specific settings shared by `CreateFunction` and
+ * `UpdateFunctionConfiguration`. `Environment` is omitted entirely when the input
+ * carries none, which on the update path leaves the function's existing variables
+ * alone; an explicit map (empty included) is sent as `{ Variables }` and replaces
+ * them.
+ */
+function configurationBody(input) {
+    return {
+        Role: input.roleArn,
+        Runtime: input.runtime,
+        Handler: input.handler,
+        MemorySize: input.memoryMb,
+        Timeout: input.timeoutSeconds,
+        ...(input.environment !== undefined ? { Environment: { Variables: input.environment } } : {}),
+    };
+}
+/**
+ * True when a `CreateFunction` failure means the function already exists, so a re-run
+ * of the create is a no-op rather than an error.
+ *
+ * The `statusCode === 409` limb is what actually does the work, and it is not
+ * belt-and-braces. Lambda answers a duplicate function name with
+ * `ResourceConflictException`, whose only status is 409 and which is the only Lambda
+ * exception at 409 - but the name never reaches `AwsError.code`, because it travels
+ * in the `x-amzn-ErrorType` header and core's `parseError` reads the body alone (see
+ * the module doc comment). So `code` is `"Http409"`, `AwsError.isAlreadyExists` -
+ * which tests `code` against `/AlreadyExists|BucketAlreadyOwnedByYou|EntityAlreadyExists|Conflict/i`
+ * - matches nothing, and a create written against it alone would report every
+ * re-bootstrap as a failure. This is a header-parsing gap and not, as in
+ * `firehose.ts`, a predicate-breadth one: `ResourceConflictException` *would* match
+ * core's regex on its `Conflict` alternative the day `parseError` learns to read the
+ * header, which is why `isAlreadyExists` is kept as the first limb rather than
+ * replaced.
+ *
+ * Named for the create path rather than as a general `isAlreadyExists` because the
+ * same exception means something else on every other operation. The service documents
+ * it as "the resource already exists, **or another operation is in progress**": on
+ * `DeleteFunction` a 409 means the function is mid-update and cannot be deleted yet,
+ * and on the two update operations it means a previous update has not finished. This
+ * predicate is applied to `createFunction` and nowhere else, so those three surface
+ * as failures instead of being reported as a torn-down or reconciled function.
+ */
+function isFunctionAlreadyExists(err) {
+    return err instanceof AwsError && (err.isAlreadyExists || err.statusCode === 409);
+}
+/** AWS Lambda function client, over the shared SigV4 transport. */
+export class LambdaClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async call(method, path, payload) {
+        const res = await this.client.send({
+            service: SERVICE,
+            method,
+            path,
+            headers: { 'content-type': 'application/json' },
+            ...(payload !== undefined ? { body: JSON.stringify(payload) } : {}),
+        });
+        const text = res.text();
+        return (text ? JSON.parse(text) : {});
+    }
+    /**
+     * Create the function with its code and configuration in one request. Idempotent:
+     * a function of the same name already existing is not an error (see
+     * `isFunctionAlreadyExists`). Its code and configuration are *not* reconciled
+     * against `input` on that path - that is what `updateFunctionCode` and
+     * `updateFunctionConfiguration` are for, and the node that owns the function
+     * decides between them on its recorded source hash.
+     *
+     * A 404 is deliberately **not** swallowed here even though `getFunction` and
+     * `deleteFunction` read one as absence. On this operation
+     * `ResourceNotFoundException` does not mean "no such function" - the function is
+     * the thing being created - it means the execution role in `roleArn` does not
+     * exist. Treating it as success would report a function that was never created,
+     * the same asymmetry `glue.ts`'s `createCatalogFederation` documents for
+     * `EntityNotFoundException`.
+     *
+     * Returns `void`, discarding the response's `FunctionArn`: it is unavailable on the
+     * already-exists path (the error body carries no ARN), so returning it from only
+     * one of the two branches would be a false economy. A caller needing the ARN either
+     * reads it back with `getFunction` - the call it made before creating anyway - or
+     * builds the fixed `arn:aws:lambda:<region>:<account-id>:function:<name>` form from
+     * what a `PluginContext` already carries, exactly as `s3tables.ts`'s
+     * `createTableBucket` argues.
+     *
+     * Tags are not accepted. The transform-function node does not tag the function, and
+     * tagging it later is `TagResource`, a separate operation this client can grow when
+     * a node needs it, rather than a parameter carried unused today.
+     */
+    async createFunction(input) {
+        try {
+            await this.call('POST', PATHS.functions, {
+                FunctionName: input.name,
+                PackageType: PACKAGE_TYPE,
+                // Nested under `Code` here; `UpdateFunctionCode` takes the same bytes as a
+                // top-level `ZipFile` instead.
+                Code: { ZipFile: encodeZip(input.zipFile) },
+                ...configurationBody(input),
+            });
+        }
+        catch (err) {
+            if (isFunctionAlreadyExists(err))
+                return;
+            rethrowWithContext(err, 'createFunction', input.name);
+        }
+    }
+    /**
+     * The function's name, ARN and lifecycle state; `undefined` when no such function
+     * exists, so the transform-function node's `read` reports absence without throwing
+     * and its `create` runs instead. Lambda answers an absent function with
+     * `ResourceNotFoundException` at HTTP 404, which `AwsError.isNotFound` matches on
+     * its status limb.
+     */
+    async getFunction(name) {
+        try {
+            const out = await this.call('GET', PATHS.function(name));
+            return normalizeFunction(out, name);
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isNotFound)
+                return undefined;
+            rethrowWithContext(err, 'getFunction', name);
+        }
+    }
+    /**
+     * Replace the function's deployment package. The zip bytes go on the wire as a
+     * **top-level** `ZipFile`, not nested under `Code` the way `CreateFunction` takes
+     * them - the two operations do not share a body shape.
+     *
+     * Nothing is swallowed. A 409 here means a previous update has not finished, not
+     * that the code is already what was sent, and a 404 means the function is gone -
+     * both are the node's to see.
+     */
+    async updateFunctionCode(name, zipFile) {
+        try {
+            await this.call('PUT', PATHS.functionCode(name), { ZipFile: encodeZip(zipFile) });
+        }
+        catch (err) {
+            rethrowWithContext(err, 'updateFunctionCode', name);
+        }
+    }
+    /**
+     * Replace the function's version-specific settings - role, runtime, handler, memory,
+     * timeout and environment. The name travels in the path, never in the body, which
+     * is why this takes it as a separate argument rather than reusing
+     * `CreateFunctionInput`.
+     *
+     * Nothing is swallowed, for the same reasons as `updateFunctionCode`.
+     */
+    async updateFunctionConfiguration(name, input) {
+        try {
+            await this.call('PUT', PATHS.functionConfiguration(name), configurationBody(input));
+        }
+        catch (err) {
+            rethrowWithContext(err, 'updateFunctionConfiguration', name);
+        }
+    }
+    /**
+     * Delete the function and every version and alias of it. No-op when it does not
+     * exist, so teardown is re-runnable.
+     *
+     * Every other failure is rethrown with context - including the 409
+     * `ResourceConflictException`, which on this operation means the function is
+     * mid-operation and cannot be deleted yet, not that it is already gone. Swallowing
+     * it (by reusing `isFunctionAlreadyExists` here) would report a live function as
+     * torn down, leaving the Firehose stream pointing at a processor the teardown
+     * claimed to have removed.
+     */
+    async deleteFunction(name) {
+        try {
+            await this.call('DELETE', PATHS.function(name));
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isNotFound)
+                return;
+            rethrowWithContext(err, 'deleteFunction', name);
+        }
+    }
+}

package/dist/aws/s3tables.d.ts

@@ -0,0 +1,120 @@
+import { type SigningClient } from 'blogwright-core';
+/**
+ * An S3 Tables bucket, as {@link S3TablesClient.getTableBucket} reports it.
+ * Narrowed from the API response on purpose: the bucket's creation timestamp
+ * and owner account are facts about the account, not about whether the node is
+ * present.
+ *
+ * The `analytics-table-bucket` node reads neither field. It decides presence on
+ * whether this resolves at all (`bucket === undefined`), and `recordTableBucket`
+ * then derives both the recorded name and the ARN from config rather than from
+ * the response - so the two agree with what the node would create, not with
+ * whatever the account happens to hold.
+ */
+export interface TableBucket {
+    arn: string;
+    name: string;
+}
+/**
+ * A namespace inside a table bucket. `tableBucketArn` is carried alongside the
+ * name because `GetNamespace`'s own response omits it (only `CreateNamespace`
+ * returns it), so the value here is the one the caller looked the namespace up
+ * by - see `normalizeNamespace`.
+ */
+export interface Namespace {
+    name: string;
+    tableBucketArn: string;
+}
+/**
+ * A table inside a namespace. The `analytics-table` node decides presence on
+ * whether this resolves at all and records `name` and `arn`; it does not read
+ * `metadataLocation`, and nothing else in the package does either - the field
+ * is carried because the API returns it, not because a caller needs it. Worth
+ * deciding whether to drop it: knip cannot see an unused interface member, so
+ * nothing here would ever flag it.
+ */
+export interface Table {
+    arn: string;
+    name: string;
+    /** Absent until the table has been written to at least once. */
+    metadataLocation: string | undefined;
+}
+/** One column of an Iceberg table's schema, in the shape `createTable` accepts. */
+export interface IcebergSchemaField {
+    readonly name: string;
+    /** An Apache Iceberg primitive type name (e.g. `"string"`, `"timestamp"`, `"date"`, `"int"`, `"long"`, `"double"`, `"boolean"`). */
+    readonly type: string;
+    /** Explicit field id, required here (see the module doc comment) so a partition field can reference it via `sourceId`. */
+    readonly id: number;
+    readonly required?: boolean | undefined;
+}
+/** The Iceberg partition transforms `IcebergPartitionField.transform` accepts. */
+export type PartitionTransform = 'identity' | 'year' | 'month' | 'day' | 'hour' | 'bucket' | 'truncate';
+/** One partition field, deriving its partition value from a schema field's `id`. */
+export interface IcebergPartitionField {
+    readonly name: string;
+    /** The schema field (`IcebergSchemaField.id`) this partition is derived from. */
+    readonly sourceId: number;
+    readonly transform: PartitionTransform;
+    readonly fieldId?: number | undefined;
+}
+/** The Iceberg schema and (optional) partition spec `createTable` writes into `metadata.iceberg`. */
+export interface IcebergTableSchema {
+    readonly fields: readonly IcebergSchemaField[];
+    readonly partitionSpec?: readonly IcebergPartitionField[] | undefined;
+}
+/** S3 Tables control-plane client, over the shared SigV4 transport. */
+export declare class S3TablesClient {
+    private readonly client;
+    constructor(client: SigningClient);
+    private call;
+    /**
+     * Create a table bucket. Idempotent: an already-existing bucket of the same
+     * name is not an error.
+     *
+     * Deliberately returns `void`, discarding the response's `arn`, rather than
+     * surfacing it: `getTableBucket` is ARN-keyed with no name-based lookup, so a
+     * caller that wants the ARN has to compute it before calling `createTableBucket`
+     * anyway - to run its own `getTableBucket` existence check first, per the usual
+     * read-then-create reconcile pattern - using the fixed
+     * `arn:aws:s3tables:<region>:<accountId>:bucket/<name>` form and the account id
+     * a `PluginContext` already carries. By the time `createTableBucket` runs, the
+     * caller already holds the ARN it needs; echoing the response's `arn` back would
+     * be redundant on the happy path, and unavailable on the already-exists path
+     * (the error body carries no `arn`), so returning it from only one of the two
+     * branches would be a false economy. `createNamespace` needs no such lookup at
+     * all (its identity is exactly its inputs); `createTable`'s identity is genuinely
+     * unrecoverable from its inputs (a table ARN carries an opaque generated id, not
+     * a name), but `getTable` is already name-keyed via `/get-table`'s query
+     * parameters, so a caller hydrates a table's ARN with a lookup, not by
+     * reconstructing it.
+     */
+    createTableBucket(name: string): Promise<void>;
+    /** Fetch a table bucket by ARN; undefined when it does not exist. */
+    getTableBucket(tableBucketArn: string): Promise<TableBucket | undefined>;
+    /** Delete a table bucket. No-op when it does not exist, so teardown is re-runnable. */
+    deleteTableBucket(tableBucketArn: string): Promise<void>;
+    /** Create a namespace in a table bucket. Idempotent: an already-existing namespace is not an error. */
+    createNamespace(tableBucketArn: string, namespace: string): Promise<void>;
+    /** Fetch a namespace by bucket ARN and name; undefined when it does not exist. */
+    getNamespace(tableBucketArn: string, namespace: string): Promise<Namespace | undefined>;
+    /** Delete a namespace. No-op when it does not exist, so teardown is re-runnable. */
+    deleteNamespace(tableBucketArn: string, namespace: string): Promise<void>;
+    /**
+     * Create an Iceberg table in a namespace, carrying its schema (and, when given,
+     * its partition spec) so the table is never created schema-less. This matters
+     * beyond correctness-in-general: Firehose matches incoming record keys to
+     * Iceberg column names *exactly* and silently routes anything that does not
+     * match to the error bucket (see the analytics plugin spec's §Record
+     * transformation), so a schema-less table here fails every subsequent record
+     * with no error surfacing anywhere - the corruption this parameter exists to
+     * prevent. Idempotent: an already-existing table is not an error (its schema is
+     * not reconciled against `schema` on that path - S3 Tables has no
+     * update-schema-on-conflict operation for `CreateTable` to fall back to).
+     */
+    createTable(tableBucketArn: string, namespace: string, name: string, schema: IcebergTableSchema): Promise<void>;
+    /** Fetch a table by bucket ARN, namespace and name; undefined when it does not exist. */
+    getTable(tableBucketArn: string, namespace: string, name: string): Promise<Table | undefined>;
+    /** Delete a table. No-op when it does not exist, so teardown is re-runnable. */
+    deleteTable(tableBucketArn: string, namespace: string, name: string): Promise<void>;
+}