blogwright-analytics 0.3.3

package/dist/nodes.d.ts

@@ -0,0 +1,404 @@
+/**
+ * The analytics plugin's resource graph. It owns the AWS resources the
+ * CloudFront-logs-to-Iceberg pipeline is built from and nothing else: the
+ * site's own bucket, distribution and log group stay in the CLI's graph
+ * (`packages/cli/src/nodes.ts`) and are never touched from here. This module
+ * carries all twelve of them, in four chains. The table chain - the S3 Tables bucket,
+ * the namespace inside it, the `page_views` table, and the Glue federation
+ * Firehose reads that table through - runs `analytics-table-bucket` ->
+ * `analytics-namespace` -> `analytics-table` ->
+ * `analytics-catalog-integration`. The transform chain - the long-lived
+ * `visitor_key` salt, the Lambda execution role whose policy names that
+ * secret's ARN, and the record-transform function itself - runs
+ * `analytics-salt-secret` -> `analytics-transform-role` ->
+ * `analytics-transform-function`. The delivery chain - the bucket every record
+ * Firehose cannot deliver lands in, the role it assumes, and the stream itself
+ * - runs `analytics-error-bucket` -> `analytics-firehose-role` ->
+ * `analytics-firehose-stream`, and joins the other two chains through the
+ * role's four grants and the stream's destination. The vended-delivery chain -
+ * the CloudWatch delivery destination pointing at that stream and the delivery
+ * joining it to the site's log source - runs `analytics-log-destination` ->
+ * `analytics-log-delivery` and hangs off the stream. All four are wired through
+ * `dependsOn`, and a node depends on every node whose recorded ARN it
+ * interpolates. {@link buildAnalyticsNodes} at the foot of this module returns
+ * the assembled set, and `plugin.ts` hands it to the SPI's `Plugin.nodes`;
+ * assembling an array is all it does - nothing here reconciles anything.
+ *
+ * **The delivery source the last chain hangs off is the site's, and this module
+ * only ever reads it.** AWS permits exactly one delivery source per
+ * distribution, so the site's CloudWatch delivery and this plugin's Firehose
+ * delivery necessarily share one, and `packages/cli/src/nodes.ts`'s
+ * `logDeliveryNode` owns it. Nothing here calls `putDeliverySource` or
+ * `deleteDeliverySource`; the source's name is read off `ctx.names` and the
+ * evidence that the site has been bootstrapped off `ctx.siteState`, the SPI's
+ * read-only view of the site's state.
+ *
+ * **Everything in this graph is created in `us-east-1`, whatever
+ * `config.region` says.** CloudFront standard logging accepts a Firehose
+ * delivery stream only in that region, so the whole pipeline - and therefore
+ * the table the stream writes into - has to live there too. The pin is
+ * enforced in exactly one place, `aws/clients.ts`, which builds every client
+ * over the host's `signingUsEast1` signer; no node here picks a region for a
+ * request. {@link ANALYTICS_REGION} below is the same region as *text*, needed
+ * only because an ARN spells its region out and because every node `title`
+ * states the pin, so the bootstrap output an operator reads carries it. Ten of
+ * the twelve titles state it as the region they are created in; the two IAM
+ * role nodes state it as the pipeline they serve, because IAM is global and
+ * "created in us-east-1" is not a property a role has (§Region pinning says so
+ * in as many words) - a title claiming otherwise would be the pin stated
+ * falsely rather than stated.
+ *
+ * The nodes are core's {@link ResourceNode} over {@link PluginContext}, so the
+ * CLI's own engine (`topoSort`/`applyGraph`/`destroyGraph`,
+ * `packages/cli/src/graph.ts`) reconciles them unchanged - this package
+ * contributes nodes, never a second engine.
+ *
+ * **Creating the namespace and the table through the S3 Tables control-plane
+ * API is a supported Firehose source.** Verified 2026-07-26 against AWS's S3
+ * Tables + Firehose walkthrough, which creates both with `aws s3tables
+ * create-namespace` and `aws s3tables create-table` and then points the
+ * delivery stream at them. This is worth recording because Firehose's
+ * considerations page carries a limitation that reads as if it forbids exactly
+ * that - "only tables created through Iceberg's GlueCatalog API". That
+ * limitation applies to plain Iceberg-on-S3 tables registered in Glue, not to
+ * S3 Tables reached through the `s3tablescatalog` federation
+ * (`analytics-catalog-integration`), which is how this pipeline reaches them.
+ * Without this note the next reader re-litigates it.
+ */
+import { type PluginContext, type ResourceNode } from 'blogwright-core';
+import { type AnalyticsConfig } from './config.js';
+/**
+ * The context every node in this module runs against: core's `PluginContext`
+ * narrowed to this plugin's own validated config block, which is what makes
+ * {@link resolveAnalyticsConfig} reachable from a node. `ResourceNode`'s own
+ * parameter is unconstrained (see core's `plugin.ts`), and the SPI's
+ * `Plugin.nodes` returns the bare `ResourceNode[]`; a node typed here is
+ * assignable to that, because `read`/`create`/`delete` are method-declared and
+ * therefore bivariant in their parameter type.
+ */
+type AnalyticsContext = PluginContext<AnalyticsConfig>;
+/** One node of the analytics graph. */
+type AnalyticsNode = ResourceNode<AnalyticsContext>;
+/**
+ * The `analytics-firehose-stream` node id. Exported, alone among the twelve,
+ * because `analytics status` reads this node's recorded outputs back out of
+ * the scoped state its `read` hydrated - the stream's delivery health - and a
+ * second copy of the string in `commands.ts` would be a state key with two
+ * homes.
+ */
+export declare const FIREHOSE_STREAM_NODE = "analytics-firehose-stream";
+/**
+ * The `analytics-log-delivery` node id. Exported for `backfill.ts`, which
+ * reads {@link CREATED_DAY_KEY} out of this node's recorded outputs: the
+ * backfill's idempotency bound and the node that writes it must name the same
+ * state entry, and a second spelling of the id is the one way that could stop
+ * being true without anything noticing.
+ */
+export declare const LOG_DELIVERY_NODE = "analytics-log-delivery";
+/** The S3 Tables bucket every analytics table lives in. */
+export declare function analyticsTableBucketNode(): AnalyticsNode;
+/** The Iceberg namespace inside the table bucket. */
+export declare function analyticsNamespaceNode(): AnalyticsNode;
+/** The `page_views` table, carrying the schema and partition `schema.ts` owns. */
+export declare function analyticsTableNode(): AnalyticsNode;
+/**
+ * The Glue `s3tablescatalog` federation Firehose reads the `page_views` table
+ * through - **the one node in this graph that adopts shared state rather than
+ * owning it.**
+ *
+ * The integration is account-and-region scoped: a single catalog federates
+ * every S3 Tables bucket in the account and Region (see
+ * {@link federationSource}), so staging, production and anything else in the
+ * account that enabled the S3 Tables integration all read through the same one.
+ * Both halves of this node's behaviour follow from that. `read` adopts an
+ * existing federation instead of creating a second one, so a second environment
+ * converges on what is already there; `delete` removes nothing, so tearing one
+ * environment down leaves every other environment's pipeline intact.
+ *
+ * It depends on `analytics-table` rather than on the bucket even though the
+ * federation covers the account rather than any one table. Two reasons: the
+ * whole table chain is then in place before anything is federated, so
+ * `CreateCatalog`'s own `EntityNotFoundException` - which on that operation
+ * means the federated entity is missing, not the catalog - cannot fire merely
+ * because the bucket had not been created yet; and `destroyGraph` reverses the
+ * order, so this node's `delete` is reached first, before the table it was
+ * enabled for is removed.
+ */
+export declare function analyticsCatalogIntegrationNode(): AnalyticsNode;
+/**
+ * The Secrets Manager secret holding the seed every `visitor_key` in the table
+ * is derived from - **the one resource in this graph that must outlive its own
+ * reconcile, and the one this module never overwrites or deletes.**
+ *
+ * `transform/visitor-key.ts` derives the per-day salt as
+ * `HMAC-SHA256(secret, day)` and `map-record.ts` hashes the viewer's address
+ * under it, so the stored value is the only thing standing between a row in
+ * `page_views` and the address it came from - the table keeps `user_agent` in
+ * the clear beside the key, and an unsalted SHA-256 over IPv4's 2^32 space is a
+ * lookup table, not a pseudonym. Two consequences shape every method below.
+ *
+ * **It is created once and never rewritten.** Replacing the value does not
+ * "rotate" anything: it orphans every `visitor_key` already written, because no
+ * row from before the change ever compares equal to a row from after it. The
+ * dashboard's unique-visitor figures would silently double at the boundary and
+ * `analytics backfill` - which re-derives a historical day's salt from this
+ * same seed - would produce rows that join to nothing. So `read` adopts, and
+ * `create` re-checks and adopts rather than trusting that the `read` before it
+ * is still true (see below). Daily turnover comes from the *derivation*, not
+ * from the store, which is why **no Secrets Manager rotation is configured**:
+ * managed rotation would mean a rotation Lambda, a schedule and a second
+ * execution role, to replace the one value that must not change.
+ *
+ * **Its `delete` removes nothing.** This is the second inert `delete` in the
+ * graph and it is inert for a different reason than
+ * `analytics-catalog-integration`'s, which is inert because the federation is
+ * shared. This one is inert because the act is asymmetric. Core's
+ * `deleteSecret` sends `ForceDeleteWithoutRecovery: true`, so there is no
+ * recovery window and nothing to undo with; keeping a secret costs cents a
+ * month and one command to remove by hand, while deleting one is unrecoverable
+ * and destroys the ability to interpret any `page_views` data that outlived the
+ * teardown - an exported copy, a table bucket whose own delete failed, or an
+ * environment torn down and re-bootstrapped, which is a routine recovery move
+ * and would otherwise come back with a different seed and no sign that
+ * anything had changed. The teardown says what it kept and how to remove it.
+ */
+export declare function analyticsSaltSecretNode(): AnalyticsNode;
+/**
+ * The transform Lambda's execution role: permission to write its own logs and
+ * to read the one secret it needs, and nothing else.
+ *
+ * It declares `dependsOn: ['analytics-salt-secret']` because its policy
+ * interpolates that node's *recorded* ARN - the implementation notes' rule that
+ * "a node depends on every node whose recorded ARN it interpolates" - and
+ * {@link requireSaltSecretArn} explains what an undeclared edge would produce.
+ */
+export declare function analyticsTransformRoleNode(): AnalyticsNode;
+/** What a reconcile of the deployed transform has to push. Both false is the common case. */
+export interface TransformUpdate {
+    /** Send `UpdateFunctionCode` - the source hash moved. */
+    readonly code: boolean;
+    /** Send `UpdateFunctionConfiguration` - the settings the function runs under moved. */
+    readonly configuration: boolean;
+}
+/**
+ * Decide what an existing transform function's reconcile has to send, from what
+ * is recorded against what the package now holds. Pure, so the decision is
+ * testable without the AWS calls - `builderImageAction`'s shape
+ * (`packages/cli/src/nodes.ts:311-321`) and its reason.
+ *
+ * **Two independent comparisons, not one.** An unchanged hash performs no code
+ * call, which is the whole point of hashing the *source*: a rebuild on another
+ * machine emits different bundle bytes from the same source, and keying the
+ * decision on those bytes would redeploy the function on every platform switch
+ * (`transform-hash.ts` argues this at length). Everything a code push could
+ * need to accompany it is covered by that hash too, because `analytics/src` is
+ * one of the hash's inputs - so the module constants above cannot change
+ * without moving it.
+ *
+ * The configuration is compared separately because one of its inputs is *not*
+ * in the hash and cannot be: `analytics.saltSecretName` comes from
+ * `blogwright.config.json`, which nothing hashes. An operator who repoints it
+ * gets a new secret, a role granted on the new ARN, and - without this
+ * comparison - a function still reading the old name out of its environment:
+ * every batch failing `GetSecretValue`, every record in Firehose's error
+ * prefix. That is the same gap `builderImageAction` carries its second `logGroup`
+ * limb for.
+ *
+ * Keeping them separate is also what keeps the common cases to a single call
+ * each, which matters more than it looks: Lambda refuses a second update while
+ * the first is still settling, so two calls in one reconcile have a window the
+ * one-call cases do not.
+ */
+export declare function transformUpdate(recorded: {
+    sourceHash: string | undefined;
+    configuration: string | undefined;
+}, desired: {
+    sourceHash: string;
+    configuration: string;
+}): TransformUpdate;
+/**
+ * The record-transform Lambda: the function Firehose runs over every CloudFront
+ * record before it reaches the `page_views` table.
+ *
+ * Its code is keyed by task 43's hash of the transform's **source**, recorded
+ * in the plugin's own state, so identical source never redeploys it - and the
+ * key that hash derives (`transformZipKey`) is recorded beside it as the
+ * artifact's name, even though the zip travels inline rather than through a
+ * bucket (see {@link MAX_INLINE_ZIP_BYTES} for why inline).
+ *
+ * It depends on `analytics-transform-role`, whose recorded ARN it runs as.
+ */
+export declare function analyticsTransformFunctionNode(): AnalyticsNode;
+/**
+ * The S3 bucket every record Firehose cannot deliver is written to - **the
+ * physical place a silent pipeline failure becomes visible.**
+ *
+ * Firehose matches incoming JSON keys to the Iceberg column names exactly and
+ * *errors* the records that do not match to this bucket rather than dropping
+ * them (the change spec quotes the behaviour). So a missing column, a table
+ * whose catalog cannot be read, a Glue grant one level too narrow - none of
+ * them raise anything an operator sees. They fill this bucket while the
+ * dashboard stays empty, and this bucket is the only place the records
+ * themselves still exist. Two properties follow.
+ *
+ * **It is in {@link ANALYTICS_REGION}, with the rest of the pipeline**, created
+ * through the plugin's own {@link s3} client rather than `ctx.clients.s3`,
+ * which signs in `config.region`.
+ *
+ * **It is not the site's environment bucket.** The bucket the CLI's own
+ * `bucketNode` creates lives in
+ * `config.region` and `S3DestinationConfiguration.BucketARN` matches
+ * `arn:.*:s3:::[\w\.\-]{1,255}` - an S3 ARN carries no region, so the API can
+ * neither express a cross-region bucket nor reject one, and Firehose's
+ * cross-region documentation covers only HTTP endpoint destinations. Pointing
+ * at the site's bucket would therefore rest the pipeline's one recovery surface
+ * on undocumented behaviour, and would put failed-record objects - which carry
+ * the raw CloudFront fields, the viewer IP among them, precisely because the
+ * transform did not run on them - inside a bucket the site serves from.
+ */
+export declare function analyticsErrorBucketNode(): AnalyticsNode;
+/**
+ * The role Firehose assumes to read the catalog, write the table, invoke the
+ * transform and store what it could not deliver - four grants, four concrete
+ * resources, no `*`.
+ *
+ * It declares `dependsOn` on the three nodes whose recorded ARNs those grants
+ * interpolate. `topoSort` drains zero-indegree nodes alphabetically
+ * (`packages/cli/src/graph.ts:35-38`), so a role declaring `dependsOn: []`
+ * would be reconciled *before* `analytics-transform-function` - `f` sorts before
+ * `t` - and the policy would interpolate an unrecorded output: a wrong
+ * permission written silently, never an error. `githubOidcRoleNode`
+ * (`packages/cli/src/nodes.ts:830`) is the precedent, declaring
+ * `cloudfront-distribution` for exactly this reason.
+ */
+export declare function analyticsFirehoseRoleNode(): AnalyticsNode;
+/**
+ * The delivery stream itself: CloudFront's records in, the transform Lambda in
+ * front of the write, the `page_views` Iceberg table out, and the plugin's own
+ * error bucket for everything that does not make it.
+ *
+ * Its four edges are the ones its payload actually reads. The role edge is the
+ * spec's own rule - the `IcebergDestinationConfiguration` interpolates the
+ * role's recorded ARN - and it also carries `analytics-error-bucket`
+ * transitively, completing the `error-bucket -> firehose-role ->
+ * firehose-stream` chain. Without the role edge the ordering would survive only
+ * on `topoSort`'s alphabetical accident (`…-role` sorts before `…-stream`), the
+ * exact coincidence-reliance the spec's implementation notes warn against.
+ *
+ * **The `AppendOnly` reconcile is written against neither AWS document.** The
+ * Firehose considerations page says the flag is settable only with
+ * `CreateDeliveryStream`; the `IcebergDestinationUpdate` API reference lists it
+ * among the fields `UpdateDestination` accepts. They cannot both be right, and a
+ * node written against either alone is a defect whichever one turns out to be.
+ * So `update` attempts the in-place update first and falls back to replacing the
+ * stream when it is refused - and only when it is refused: the re-read that
+ * follows a successful update sits outside that `try`, because failing it is not
+ * a rejection and replacing a stream that was updated correctly would be pure
+ * loss. The order matters: `UpdateDestination` keeps the stream's ARN, while a
+ * replacement gets a new one - so the CloudFront log delivery task 53 builds
+ * would have to be repointed, and the records arriving during the gap are lost.
+ * Which path ran is in the log line.
+ */
+export declare function analyticsFirehoseStreamNode(): AnalyticsNode;
+/**
+ * The state key holding the UTC day this plugin's delivery was **first**
+ * created - the idempotency bound the change spec's §Backfill of historical
+ * logs defines and task 61 reads.
+ *
+ * Written once and never advanced. Backfill inserts only whole days *strictly
+ * before* it, on the reasoning that Firehose received nothing before its
+ * delivery existed, so the two paths' row sets are disjoint. The two error
+ * directions are not symmetric, which is why the rule is write-once rather
+ * than keep-current: a bound that is too *early* loses at most the day at the
+ * seam, which the spec states and accepts, while a bound that moved *later*
+ * would let backfill insert days Firehose had already delivered and silently
+ * double every row in them. So a second reconcile, a re-created delivery and
+ * the destination node's Conflict retry all leave it exactly as it was.
+ *
+ * `read` never writes it either, even though it hydrates the rest of this
+ * node's outputs off the live delivery: `DescribeDeliveries` reports no
+ * creation date, so a delivery found already attached to a state file that
+ * lost this key leaves task 61 with no bound and an actionable refusal. That
+ * is the loud direction, and it is preferred to today's date, which would be a
+ * bound that moved later.
+ *
+ * Exported since task 61, which reads it. It was deliberately module-private
+ * while nothing consumed it - an exported constant with no consumer is what
+ * `pnpm knip` catches - but a private constant restated in its reader is worse
+ * than an exported one: the two spellings would have to agree and nothing
+ * would check that they did.
+ */
+export declare const CREATED_DAY_KEY = "createdDay";
+/**
+ * The CloudWatch delivery destination the site's CloudFront records are
+ * delivered to - **this plugin's own, alongside the site's and never in place
+ * of it.**
+ *
+ * Its one edge is the node whose recorded ARN it points at. `PutDeliveryDestination`
+ * accepts a `destinationResourceArn` for a resource that does not exist yet, so
+ * without the edge the destination would be created against `undefined` and the
+ * first symptom would be records going nowhere - see {@link requireStreamArn}.
+ *
+ * The output format is the one thing about a destination that cannot be
+ * changed once it exists, which is why `update` replaces rather than mutates
+ * and why the configured format is recorded beside the ARN in the first place.
+ */
+export declare function analyticsLogDestinationNode(): AnalyticsNode;
+/**
+ * The delivery joining the site's existing delivery source to this plugin's
+ * destination - **a second delivery on a source the plugin reads, never
+ * creates, never repoints and never deletes.**
+ *
+ * `putDeliverySource` is not called here and must never be. AWS permits one
+ * delivery source per distribution and the site's node owns it
+ * (`packages/cli/src/nodes.ts`'s `logDeliveryNode`); this node reads its name
+ * off `ctx.names` and attaches a second delivery beside the site's CloudWatch
+ * one. The site's copy is left with the field list AWS defaults to, which is
+ * deliberate and is `schema.ts`'s to explain.
+ *
+ * There is no `update`. CloudWatch Logs has no `UpdateDelivery`: the record
+ * fields a delivery selects are fixed when it is created, exactly as the
+ * `page_views` table's schema is fixed when *it* is created
+ * (`aws/s3tables.ts`'s `createTable` reconciles no existing schema). Changing
+ * the column set is a rebuild of this pipeline in both places, not a
+ * reconcile, and pretending otherwise in one of the two would be worse than
+ * saying so in both.
+ */
+export declare function analyticsLogDeliveryNode(): AnalyticsNode;
+/**
+ * The plugin's twelve resource nodes, assembled in the order the change spec's
+ * §Analytics pipeline → Resource nodes table lists them. This is what
+ * `Plugin.nodes` (`plugin.ts`) hands the CLI's generic `analytics bootstrap`
+ * and `analytics destroy` verbs, and it is the whole of what this package
+ * contributes to a reconcile: the engine that walks them - `topoSort`,
+ * `applyGraph`, `destroyGraph` - is the CLI's own and is never reimplemented
+ * here.
+ *
+ * **The returned order is itself a topological order**, and that is a property
+ * of this array rather than a coincidence of the table's layout: every node's
+ * `dependsOn` names only nodes that appear EARLIER in it. That is worth stating
+ * because it is exactly the witness `topoSort`'s two failure modes are the
+ * absence of - a dependency naming a node outside the set, and a cycle - so a
+ * test that checks it has proved the set passes `topoSort` without running a
+ * second copy of `topoSort` to find out. `applyGraph` sorts the array again
+ * regardless and does not rely on the order it arrives in; nothing here may
+ * assume the reconcile follows this sequence, only that this sequence is a
+ * legal one.
+ *
+ * **No `ctx` parameter, deliberately.** The SPI declares `nodes?(ctx)` and the
+ * CLI calls it with one, so this function is assignable to it as written - a
+ * zero-argument function satisfies a one-argument signature. None of the twelve
+ * factories needs a context to be *built*: each reads `ctx` inside `read`,
+ * `create`, `update` and `delete`, when the reconcile is actually running. A
+ * parameter accepted and ignored here would be an unused binding and, worse, a
+ * claim that the SET varies with the context - it does not, and `analytics
+ * status` and `analytics destroy` both depend on it not doing so. (The plan's
+ * task 54 spells this function `buildAnalyticsNodes(ctx)`; the argument is what
+ * changed, not the wiring.)
+ *
+ * A fresh array of fresh nodes on every call, matching `buildNodes`
+ * (`packages/cli/src/nodes.ts`): a node object carries no state between
+ * reconciles, and two calls in one process must not share one.
+ */
+export declare function buildAnalyticsNodes(): AnalyticsNode[];
+export {};