blogwright-analytics 0.3.3

package/dist/aws/glue.d.ts

@@ -0,0 +1,103 @@
+import { type SigningClient } from 'blogwright-core';
+/**
+ * A catalog federation as this plugin reads it, mapped out of Glue's `Catalog` shape
+ * so the catalog-integration node decides whether to adopt without re-reading the raw
+ * response. `sourceIdentifier` and `connectionName` are what make that decision
+ * possible: a catalog of the right name that is not federated at all, or federated
+ * somewhere else, is not something to adopt, and both keys are absent in that case.
+ */
+export interface CatalogFederation {
+    /** The catalog's name (`s3tablescatalog` for this plugin's federation). */
+    readonly name: string;
+    /**
+     * The catalog's own ARN (`Catalog.ResourceArn`), in the
+     * `arn:aws:glue:<region>:<account-id>:catalog/<name>` form. Empty string when the
+     * service reports none.
+     */
+    readonly resourceArn: string;
+    /**
+     * `FederatedCatalog.Identifier` - the S3 Tables resource the catalog federates, as
+     * `arn:aws:s3tables:<region>:<account-id>:bucket/*`. Undefined when the catalog
+     * exists but carries no `FederatedCatalog` at all.
+     */
+    readonly sourceIdentifier: string | undefined;
+    /** `FederatedCatalog.ConnectionName` - `aws:s3tables` for this federation. Undefined when the catalog is not federated. */
+    readonly connectionName: string | undefined;
+}
+/**
+ * AWS Glue Data Catalog client for the S3 Tables federation, over the shared SigV4
+ * transport.
+ *
+ * Both narrowings below use `AwsError`'s predicates unmodified, unlike this module's
+ * two siblings, and that is a property of the service rather than luck: Glue is
+ * AWS-JSON, so its error body carries `{"__type":"EntityNotFoundException",...}` and
+ * core's `parseError` (`packages/core/src/aws/signer.ts`) reads a real exception name
+ * into `AwsError.code` - where `s3tables.ts` gets `Http<status>` because S3 Tables
+ * puts the name in an `x-amzn-ErrorType` header the parser never reads. And Glue's
+ * names happen to fall inside both patterns: `EntityNotFoundException` matches
+ * `isNotFound`'s `/NotFound/i` (`packages/core/src/aws/errors.ts:24`), while both
+ * `AlreadyExistsException` *and* `FederatedResourceAlreadyExistsException` - the two
+ * distinct duplicates `CreateCatalog` documents - match `isAlreadyExists`'s
+ * `/AlreadyExists/i` (`errors.ts:32`). So no local predicate is needed here and core's
+ * regex, which the site's own bootstrap shares, is left alone.
+ *
+ * `statusCode` is no help either way and is never narrowed on: every Glue exception is
+ * HTTP 400 except `InternalServiceException` at 500, so `isNotFound`'s `=== 404` limb
+ * and any `=== 409` limb are dead on this service - the code is the only signal. Glue
+ * also returns its request id only in the `x-amzn-requestid` header, which
+ * `parseError` does not read, so `AwsError.requestId` is always `undefined` here.
+ */
+export declare class GlueClient {
+    private readonly client;
+    constructor(client: SigningClient);
+    private call;
+    /**
+     * Create the `s3tablescatalog` federation over an S3 Tables bucket resource.
+     * `tableBucketArn` is the `FederatedCatalog.Identifier`, and AWS's integration
+     * procedure passes the account-and-region wildcard
+     * `arn:aws:s3tables:<region>:<account-id>:bucket/*` there: one catalog federates
+     * every table bucket in the account and Region, mounting each as a child catalog.
+     * This client sends whatever the caller passes rather than building the wildcard
+     * itself - the node owns the account id and Region.
+     *
+     * Idempotent: an already-existing federation resolves rather than throwing, because
+     * the integration is **account-and-region-scoped shared state**. Two blogwright
+     * environments in one account share the single `s3tablescatalog`, as does anything
+     * else in that account that enabled the integration, so a second environment's
+     * bootstrap must adopt what is there instead of fighting over it. Both duplicate
+     * exceptions are covered: `AlreadyExistsException` when a catalog of that name
+     * exists, and `FederatedResourceAlreadyExistsException` when the federation itself
+     * is already registered (which is what a second run against a console-enabled
+     * account hits).
+     *
+     * Nothing else is swallowed. In particular `EntityNotFoundException`, which
+     * `CreateCatalog` also documents, means something entirely different here than it
+     * does on `getCatalogFederation` - not "no such catalog" but "the entity this
+     * catalog would federate does not exist", i.e. the S3 Tables resource in
+     * `tableBucketArn` is wrong. Treating that as success would report a federation that
+     * was never created.
+     *
+     * Returns `void`: `CreateCatalog`'s success response is an empty body, so there is
+     * nothing to return, and a caller that needs the catalog's ARN reads it back with
+     * `getCatalogFederation` - which is the call it made before creating anyway.
+     */
+    createCatalogFederation(name: string, tableBucketArn: string): Promise<void>;
+    /**
+     * Look the federation up by catalog name; `undefined` when it does not exist, so the
+     * catalog-integration node adopts an existing federation instead of creating one, in
+     * the `packages/core/src/aws/secretsmanager.ts:78-89` shape.
+     *
+     * The name *is* the id: `GetCatalog` is keyed by `CatalogId`, and for a catalog
+     * created directly under the account that id is the catalog's own name (AWS's
+     * verification step for the integration is literally
+     * `aws glue get-catalog --catalog-id s3tablescatalog`). It takes no bucket ARN -
+     * `GetCatalogRequest` has exactly one member.
+     *
+     * Only `EntityNotFoundException` reads as absent. `FederationSourceException` in
+     * particular is rethrown even though its `FederationSourceErrorCode` can itself be
+     * `EntityNotFoundException`: `parseError` reads the outer `__type`, so `code` is the
+     * wrapper name, and a federation source that failed is a broken federation to
+     * surface, not a missing one to silently re-create.
+     */
+    getCatalogFederation(name: string): Promise<CatalogFederation | undefined>;
+}

package/dist/aws/glue.js

@@ -0,0 +1,225 @@
+import { AwsError } from 'blogwright-core';
+import { rethrowWithContext } from './errors.js';
+/**
+ * AWS Glue Data Catalog client, cut down to the one thing this plugin needs: the
+ * `s3tablescatalog` federation Firehose writes the `page_views` table through.
+ * Firehose reaches an S3 Tables table only via a Glue catalog
+ * (`IcebergDestinationConfiguration.CatalogConfiguration.CatalogARN`), never via
+ * the S3 Tables API directly, so without this federation the delivery stream has
+ * nothing to point at. It exposes exactly two operations - create the federation
+ * and look one up - because `analytics-catalog-integration` is a read-then-adopt
+ * node and needs nothing else; no update, no delete (the change spec makes that
+ * node's `delete()` a no-op, since the federation is account-and-region scoped
+ * shared state that other environments and other tools also depend on).
+ *
+ * It lives in `blogwright-analytics`, not in core: core's `SIGNING_NAMES` gains no
+ * `glue` key, and every request signs through the `{ service: 'glue', signingName:
+ * 'glue' }` descriptor the plugin transport seam accepts (see
+ * `packages/core/src/aws/endpoint.ts`'s `ServiceDescriptor`), which resolves to the
+ * canonical `glue.<region>.amazonaws.com` host.
+ *
+ * Protocol: AWS JSON 1.1 - `POST /` with `content-type: application/x-amz-json-1.1`
+ * and an `x-amz-target: AWSGlue.<Operation>` header, exactly as
+ * `packages/core/src/aws/secretsmanager.ts` and `logs.ts` do for their services.
+ * `AWSGlue` is the service's own target prefix (`glue-2017-03-31`'s `targetPrefix`),
+ * and both operations are `POST /` despite Glue's reference calling them "Get" and
+ * "Create".
+ *
+ * Operation names and body keys below are verified against the Glue API reference
+ * (`CreateCatalog`, `GetCatalog`, and the `CatalogInput`, `FederatedCatalog`,
+ * `PrincipalPermissions` and `Catalog` shapes they nest) and against AWS's own
+ * documented S3 Tables integration procedure. No SDK validates them here and a
+ * transport-mocked test can only assert the body this module itself builds, so the
+ * reference is the only thing that catches a wrong or missing key - and here a wrong
+ * key produces a *silently misconfigured federation*, not an error: `CatalogInput`
+ * has no required members at all, so a `CreateCatalog` that omitted
+ * `FederatedCatalog` entirely would return HTTP 200 and leave an empty non-federated
+ * catalog behind under the right name, which `getCatalogFederation` would then
+ * happily adopt.
+ *
+ * Two easy-to-miss spellings are pinned deliberately:
+ * - `Name` is a *sibling* of `CatalogInput`, not a member of it. `CatalogInput`
+ *   carries no name; putting one inside it is silently ignored.
+ * - `CatalogNameString`'s pattern is `^(?!(.*[.\/\\]|aws:)).*$` - a catalog name may
+ *   not start with `aws:`. That restriction does *not* apply to
+ *   `FederatedCatalog.ConnectionName`, which is exactly `aws:s3tables`; the two are
+ *   different fields with different patterns.
+ *
+ * The floci emulator does not implement this service, so it is covered by transport
+ * mocks in tests.
+ */
+const SERVICE = { service: 'glue', signingName: 'glue' };
+/** The service's AWS-JSON target prefix; every `x-amz-target` is `${TARGET}.<Operation>`. */
+const TARGET = 'AWSGlue';
+/**
+ * The AWS-managed connection that federates S3 Tables into the Data Catalog, sent as
+ * `FederatedCatalog.ConnectionName`. Hard-coded rather than a parameter because this
+ * client exists only for the S3 Tables federation; any other connection would make
+ * `createCatalogFederation` a different operation. `FederatedCatalog.ConnectionType`
+ * is deliberately not sent - AWS's documented S3 Tables integration omits it, and the
+ * connection name alone identifies the source.
+ */
+const S3_TABLES_CONNECTION = 'aws:s3tables';
+/**
+ * The default permissions that put the federated catalog under **IAM access control**
+ * rather than Lake Formation grants, sent as both
+ * `CatalogInput.CreateDatabaseDefaultPermissions` and `CreateTableDefaultPermissions`.
+ *
+ * Load-bearing, not decoration. `CatalogInput` marks both fields optional, so omitting
+ * them succeeds - and leaves the catalog under Lake Formation control, where every
+ * read and write needs a grant this plugin never provisions. Firehose's delivery role
+ * would be denied on write and the change spec's whole "requires `s3tables`
+ * permissions but no Lake Formation grant" assumption would fail, with the only
+ * symptom a stream quietly routing every record to the error bucket. AWS's own S3
+ * Tables integration procedure sets both to `IAM_ALLOWED_PRINCIPALS` with `ALL` for
+ * exactly this reason.
+ *
+ * `AllowFullTableExternalDataAccess` is deliberately *not* sent alongside them. It
+ * only opens Lake-Formation-registered S3 locations to third-party engines, and the
+ * one third-party reader here (DuckDB) attaches through S3 Tables' own endpoint, not
+ * through Glue credential vending - so setting it would widen access this pipeline
+ * never uses. Note if it is ever needed that it is a **string** enum, `"True"` or
+ * `"False"`, not a boolean.
+ */
+const IAM_DEFAULT_PERMISSIONS = [
+    { Principal: { DataLakePrincipalIdentifier: 'IAM_ALLOWED_PRINCIPALS' }, Permissions: ['ALL'] },
+];
+/**
+ * Map `GetCatalog`'s response onto the domain value.
+ *
+ * A 200 is the existence signal: `GetCatalogResponse.Catalog` is optional in the
+ * service model, but a 200 carrying no catalog is neither documented nor observed, so
+ * an absent field falls back rather than inventing a second "does not exist" answer
+ * next to `EntityNotFoundException` - the same call this module's siblings make
+ * (`s3tables.ts`'s `normalizeTable`, `firehose.ts`'s `describeDeliveryStream`).
+ */
+function normalizeCatalog(out, fallbackName) {
+    const catalog = out.Catalog;
+    return {
+        name: catalog?.Name ?? fallbackName,
+        resourceArn: catalog?.ResourceArn ?? '',
+        sourceIdentifier: catalog?.FederatedCatalog?.Identifier,
+        connectionName: catalog?.FederatedCatalog?.ConnectionName,
+    };
+}
+/**
+ * AWS Glue Data Catalog client for the S3 Tables federation, over the shared SigV4
+ * transport.
+ *
+ * Both narrowings below use `AwsError`'s predicates unmodified, unlike this module's
+ * two siblings, and that is a property of the service rather than luck: Glue is
+ * AWS-JSON, so its error body carries `{"__type":"EntityNotFoundException",...}` and
+ * core's `parseError` (`packages/core/src/aws/signer.ts`) reads a real exception name
+ * into `AwsError.code` - where `s3tables.ts` gets `Http<status>` because S3 Tables
+ * puts the name in an `x-amzn-ErrorType` header the parser never reads. And Glue's
+ * names happen to fall inside both patterns: `EntityNotFoundException` matches
+ * `isNotFound`'s `/NotFound/i` (`packages/core/src/aws/errors.ts:24`), while both
+ * `AlreadyExistsException` *and* `FederatedResourceAlreadyExistsException` - the two
+ * distinct duplicates `CreateCatalog` documents - match `isAlreadyExists`'s
+ * `/AlreadyExists/i` (`errors.ts:32`). So no local predicate is needed here and core's
+ * regex, which the site's own bootstrap shares, is left alone.
+ *
+ * `statusCode` is no help either way and is never narrowed on: every Glue exception is
+ * HTTP 400 except `InternalServiceException` at 500, so `isNotFound`'s `=== 404` limb
+ * and any `=== 409` limb are dead on this service - the code is the only signal. Glue
+ * also returns its request id only in the `x-amzn-requestid` header, which
+ * `parseError` does not read, so `AwsError.requestId` is always `undefined` here.
+ */
+export class GlueClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async call(op, payload) {
+        const res = await this.client.send({
+            service: SERVICE,
+            method: 'POST',
+            path: '/',
+            headers: {
+                'content-type': 'application/x-amz-json-1.1',
+                'x-amz-target': `${TARGET}.${op}`,
+            },
+            body: JSON.stringify(payload),
+        });
+        const text = res.text();
+        return (text ? JSON.parse(text) : {});
+    }
+    /**
+     * Create the `s3tablescatalog` federation over an S3 Tables bucket resource.
+     * `tableBucketArn` is the `FederatedCatalog.Identifier`, and AWS's integration
+     * procedure passes the account-and-region wildcard
+     * `arn:aws:s3tables:<region>:<account-id>:bucket/*` there: one catalog federates
+     * every table bucket in the account and Region, mounting each as a child catalog.
+     * This client sends whatever the caller passes rather than building the wildcard
+     * itself - the node owns the account id and Region.
+     *
+     * Idempotent: an already-existing federation resolves rather than throwing, because
+     * the integration is **account-and-region-scoped shared state**. Two blogwright
+     * environments in one account share the single `s3tablescatalog`, as does anything
+     * else in that account that enabled the integration, so a second environment's
+     * bootstrap must adopt what is there instead of fighting over it. Both duplicate
+     * exceptions are covered: `AlreadyExistsException` when a catalog of that name
+     * exists, and `FederatedResourceAlreadyExistsException` when the federation itself
+     * is already registered (which is what a second run against a console-enabled
+     * account hits).
+     *
+     * Nothing else is swallowed. In particular `EntityNotFoundException`, which
+     * `CreateCatalog` also documents, means something entirely different here than it
+     * does on `getCatalogFederation` - not "no such catalog" but "the entity this
+     * catalog would federate does not exist", i.e. the S3 Tables resource in
+     * `tableBucketArn` is wrong. Treating that as success would report a federation that
+     * was never created.
+     *
+     * Returns `void`: `CreateCatalog`'s success response is an empty body, so there is
+     * nothing to return, and a caller that needs the catalog's ARN reads it back with
+     * `getCatalogFederation` - which is the call it made before creating anyway.
+     */
+    async createCatalogFederation(name, tableBucketArn) {
+        try {
+            await this.call('CreateCatalog', {
+                Name: name,
+                CatalogInput: {
+                    FederatedCatalog: {
+                        Identifier: tableBucketArn,
+                        ConnectionName: S3_TABLES_CONNECTION,
+                    },
+                    CreateDatabaseDefaultPermissions: IAM_DEFAULT_PERMISSIONS,
+                    CreateTableDefaultPermissions: IAM_DEFAULT_PERMISSIONS,
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isAlreadyExists)
+                return;
+            rethrowWithContext(err, 'createCatalogFederation', name);
+        }
+    }
+    /**
+     * Look the federation up by catalog name; `undefined` when it does not exist, so the
+     * catalog-integration node adopts an existing federation instead of creating one, in
+     * the `packages/core/src/aws/secretsmanager.ts:78-89` shape.
+     *
+     * The name *is* the id: `GetCatalog` is keyed by `CatalogId`, and for a catalog
+     * created directly under the account that id is the catalog's own name (AWS's
+     * verification step for the integration is literally
+     * `aws glue get-catalog --catalog-id s3tablescatalog`). It takes no bucket ARN -
+     * `GetCatalogRequest` has exactly one member.
+     *
+     * Only `EntityNotFoundException` reads as absent. `FederationSourceException` in
+     * particular is rethrown even though its `FederationSourceErrorCode` can itself be
+     * `EntityNotFoundException`: `parseError` reads the outer `__type`, so `code` is the
+     * wrapper name, and a federation source that failed is a broken federation to
+     * surface, not a missing one to silently re-create.
+     */
+    async getCatalogFederation(name) {
+        try {
+            const out = await this.call('GetCatalog', { CatalogId: name });
+            return normalizeCatalog(out, name);
+        }
+        catch (err) {
+            if (err instanceof AwsError && err.isNotFound)
+                return undefined;
+            rethrowWithContext(err, 'getCatalogFederation', name);
+        }
+    }
+}

package/dist/aws/lambda.d.ts

@@ -0,0 +1,132 @@
+import { type SigningClient } from 'blogwright-core';
+/**
+ * The version-specific settings shared by `CreateFunction` and
+ * `UpdateFunctionConfiguration` - the two operations that carry exactly these keys,
+ * one nested in a create body and one as the whole body of the configuration PUT.
+ * Expressed once so the pair cannot drift.
+ */
+export interface FunctionConfigurationInput {
+    /** ARN of the function's execution role (`Role`). */
+    readonly roleArn: string;
+    /** Runtime identifier, e.g. `nodejs22.x` (`Runtime`). */
+    readonly runtime: string;
+    /** Entry point, `<file>.<export>` for a Node runtime (`Handler`). */
+    readonly handler: string;
+    /** Memory available to the function in **MB** (`MemorySize`; 128-32768, any multiple of 1 MB). */
+    readonly memoryMb: number;
+    /** Maximum run time in **seconds** (`Timeout`; the service caps it at 900). */
+    readonly timeoutSeconds: number;
+    /**
+     * Environment variables (`Environment.Variables`). Absent and empty mean different
+     * things to the service on an update and are sent differently: omitting the key
+     * leaves the function's existing variables untouched, while an explicit map
+     * replaces them wholesale - so an empty map *clears* them.
+     */
+    readonly environment?: Record<string, string> | undefined;
+}
+/** Everything `CreateFunction` needs on top of the shared configuration. */
+export interface CreateFunctionInput extends FunctionConfigurationInput {
+    /** The function's name (`FunctionName`), also the name every other operation addresses it by. */
+    readonly name: string;
+    /**
+     * The deployment package as raw zip bytes, sent inline. This client base64-encodes
+     * them into the wire's blob member itself - that translation is its concern, not
+     * its callers'. Inline rather than an S3 code location because Lambda requires the
+     * code bucket to sit in the function's own region while the site's bucket is in
+     * `config.region` and this function is pinned to us-east-1; the node that reads the
+     * bundle owns the size guard against the inline-payload limit.
+     */
+    readonly zipFile: Uint8Array;
+}
+/**
+ * A function's lifecycle state in this repo's vocabulary rather than the service's
+ * mixed case, mirroring how `firehose.ts` maps `DeliveryStreamStatus`. It is not
+ * decoration: a function that exists but is `failed` is not something the
+ * transform-function node should adopt as reconciled (the pipeline would then route
+ * every record to the error bucket with nothing surfacing as an error), and an update
+ * against a `pending` function is answered with a 409. `unknown` covers a state the
+ * service adds later - reporting an unrecognised state as unknown is honest, where
+ * mapping it onto one of the eight would not be.
+ */
+export type FunctionState = 'pending' | 'active' | 'inactive' | 'failed' | 'deactivating' | 'deactivated' | 'active-non-invocable' | 'deleting' | 'unknown';
+/** The narrow view of `GetFunction` the transform-function node needs. */
+export interface LambdaFunction {
+    readonly name: string;
+    /** The function's ARN (`Configuration.FunctionArn`). Empty string when the service reports none. */
+    readonly arn: string;
+    readonly state: FunctionState;
+}
+/** AWS Lambda function client, over the shared SigV4 transport. */
+export declare class LambdaClient {
+    private readonly client;
+    constructor(client: SigningClient);
+    private call;
+    /**
+     * 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.
+     */
+    createFunction(input: CreateFunctionInput): Promise<void>;
+    /**
+     * 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.
+     */
+    getFunction(name: string): Promise<LambdaFunction | undefined>;
+    /**
+     * 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.
+     */
+    updateFunctionCode(name: string, zipFile: Uint8Array): Promise<void>;
+    /**
+     * 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`.
+     */
+    updateFunctionConfiguration(name: string, input: FunctionConfigurationInput): Promise<void>;
+    /**
+     * 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.
+     */
+    deleteFunction(name: string): Promise<void>;
+}