blogwright-analytics 0.3.3

package/dist/schema.js

@@ -0,0 +1,154 @@
+/**
+ * The single home for the `page_views` Iceberg table: its column set, its
+ * `day` partition, the CloudFront standard-logging (v2) fields the delivery
+ * selects, and the mapping between the two. The transform Lambda, the table
+ * node and the delivery node all read these constants instead of restating
+ * them - see [§Table schema](../../../.specs/changes/merged/2026-07-26-analytics_plugin.md).
+ *
+ * Why this file is worth being careful with: Firehose matches incoming JSON
+ * keys to Iceberg column names **exactly** and silently discards any field
+ * that does not match a column - no error, no dead-letter record, nothing
+ * that shows up in a log. A typo here does not fail loudly; it fills a
+ * column with nulls forever, and nothing points back at this file as the
+ * cause. Column names are lowercase throughout - an S3 Tables catalog
+ * requirement, not a style choice.
+ *
+ * `cs(Cookie)` and `x-forwarded-for` carry personal data and have no
+ * analytic use, so they are never selected: they never reach Firehose, the
+ * transform, or the table. This governs the analytics delivery only. The
+ * site's existing CloudWatch delivery (`packages/cli/src/nodes.ts`'s
+ * `logDeliveryNode`, wired through `packages/core/src/aws/logs.ts`'s
+ * `createDelivery`) is created with no `recordFields`, so AWS's default
+ * field list - which includes both excluded fields - still applies to that
+ * copy. Narrowing that is a separate change to the site's node, not this
+ * one; do not "fix" that inconsistency here.
+ *
+ * Field names are verified against AWS's CloudFront standard-logging (v2)
+ * documentation (docs.aws.amazon.com/AmazonCloudFront, "Configure standard
+ * logging (v2)" and "Standard logging reference", current as of 2026-08-30):
+ * the `recordFields` the CreateDelivery API accepts, and the field
+ * descriptions in the log-file-field reference.
+ *
+ * Pure data and pure functions only: no `node:` builtin, no vendor SDK, no
+ * `fetch`.
+ */
+/**
+ * The `page_views` table, in the order the spec's `PageView` `$defs` block
+ * lists it. `required` is `true` exactly for the spec's `PageView.required`
+ * set (`event_time`, `day`, `host`, `uri`, `status`); every other column may
+ * be null - CloudFront itself writes `-` for several of these when a request
+ * has nothing to say (no referrer, no query string, and so on).
+ */
+export const PAGE_VIEWS_COLUMNS = [
+    { name: 'event_time', icebergType: 'timestamp', required: true },
+    { name: 'day', icebergType: 'date', required: true },
+    { name: 'host', icebergType: 'string', required: true },
+    { name: 'uri', icebergType: 'string', required: true },
+    { name: 'query', icebergType: 'string', required: false },
+    { name: 'method', icebergType: 'string', required: false },
+    { name: 'status', icebergType: 'int', required: true },
+    { name: 'referrer', icebergType: 'string', required: false },
+    { name: 'user_agent', icebergType: 'string', required: false },
+    { name: 'country', icebergType: 'string', required: false },
+    { name: 'asn', icebergType: 'string', required: false },
+    { name: 'edge_location', icebergType: 'string', required: false },
+    { name: 'result_type', icebergType: 'string', required: false },
+    { name: 'bytes_sent', icebergType: 'long', required: false },
+    { name: 'time_taken', icebergType: 'double', required: false },
+    { name: 'content_type', icebergType: 'string', required: false },
+    { name: 'protocol', icebergType: 'string', required: false },
+    { name: 'request_id', icebergType: 'string', required: false },
+    { name: 'visitor_key', icebergType: 'string', required: false },
+    { name: 'is_bot', icebergType: 'boolean', required: false },
+];
+/** `page_views` is partitioned by this column. */
+export const PAGE_VIEWS_PARTITION_COLUMN = 'day';
+/**
+ * The CloudFront viewer-IP field. Selected so the transform can derive
+ * `visitor_key` from it (IP + user agent + a secret daily salt); the raw
+ * value is discarded by the transform and never written to any column, so
+ * it has no entry in `FIELD_TO_COLUMN`.
+ */
+export const VIEWER_IP_FIELD = 'c-ip';
+/**
+ * The CloudFront millisecond-epoch timestamp field. Selected so the
+ * transform can derive both `event_time` and the `day` partition from it;
+ * because it feeds two columns rather than renaming into one, it has no
+ * entry in `FIELD_TO_COLUMN` either. Exported for its one consumer,
+ * `transform/map-record.ts`, which reads the field off the record and must
+ * not spell its name a second time - the field name is not a valid column
+ * name, so a divergence between the two spellings would silently stop
+ * filling `event_time` and `day`.
+ */
+export const TIMESTAMP_MS_FIELD = 'timestamp(ms)';
+/**
+ * Selected CloudFront fields that feed a `DERIVED_COLUMNS` entry instead of
+ * being renamed 1:1 into a column of their own.
+ */
+export const DERIVATION_ONLY_FIELDS = [VIEWER_IP_FIELD, TIMESTAMP_MS_FIELD];
+/**
+ * The CloudFront standard-logging (v2) field name each `page_views` column
+ * is filled from, a straight rename with no other transformation. Field
+ * names and meanings are as AWS documents them under "Standard logging
+ * reference":
+ *
+ * - `x-host-header` (not `cs(Host)`) is the Host header the viewer actually
+ *   sent - the alternate domain name (CNAME) when the site has one, and the
+ *   distribution's own domain otherwise. `cs(Host)` always reports the raw
+ *   CloudFront distribution domain regardless of what the viewer requested,
+ *   which would make `host` a constant for every custom-domain site.
+ * - `x-edge-result-type` (not `x-edge-response-result-type` or
+ *   `x-edge-detailed-result-type`) is the standard hit/miss/error
+ *   classification after the response finished sending - the field AWS's own
+ *   sample cache-hit-ratio queries group by. The other two exist for
+ *   diagnosing mid-response client disconnects and origin-error detail,
+ *   which this table does not carry a column for.
+ * - `sc-bytes` (not `cs-bytes` or `sc-content-len`) is the total bytes
+ *   CloudFront sent to the viewer, matching `bytes_sent`; `cs-bytes` is the
+ *   viewer's request size and `sc-content-len` is only the `Content-Length`
+ *   header value.
+ */
+export const FIELD_TO_COLUMN = {
+    'x-host-header': 'host',
+    'cs-uri-stem': 'uri',
+    'cs-uri-query': 'query',
+    'cs-method': 'method',
+    'sc-status': 'status',
+    'cs(Referer)': 'referrer',
+    'cs(User-Agent)': 'user_agent',
+    'c-country': 'country',
+    asn: 'asn',
+    'x-edge-location': 'edge_location',
+    'x-edge-result-type': 'result_type',
+    'sc-bytes': 'bytes_sent',
+    'time-taken': 'time_taken',
+    'sc-content-type': 'content_type',
+    'cs-protocol': 'protocol',
+    'x-edge-request-id': 'request_id',
+};
+/**
+ * The CloudFront fields the analytics delivery selects: every
+ * `FIELD_TO_COLUMN` key plus the two derivation-only inputs. `cs(Cookie)`
+ * and `x-forwarded-for` are deliberately absent - see the module doc comment.
+ */
+export const CLOUDFRONT_RECORD_FIELDS = [
+    ...Object.keys(FIELD_TO_COLUMN),
+    ...DERIVATION_ONLY_FIELDS,
+];
+/**
+ * The four `page_views` columns no CloudFront field maps to 1:1 - each is
+ * computed by the transform from one or more selected fields rather than
+ * renamed from a single one:
+ *
+ * - `event_time` and `day` are both derived from `timestamp(ms)`.
+ * - `visitor_key` is a salted hash of `c-ip`, `cs(User-Agent)` and a secret
+ *   daily salt - no single field determines it.
+ * - `is_bot` is a user-agent match against `cs(User-Agent)`, which already
+ *   has its own entry in `FIELD_TO_COLUMN` (-> `user_agent`).
+ */
+export const DERIVED_COLUMNS = [
+    'event_time',
+    'day',
+    'visitor_key',
+    'is_bot',
+];

package/dist/server.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The package's **edge**: the one module that imports `node:http`, and the one
+ * place an HTTP request becomes a call on the {@link AnalyticsQuery} port.
+ * Everything below the port - `queries.ts`, `schema.ts`, the transform, the
+ * nodes - is reached only through {@link createDashboardServer}, so a reviewer
+ * who wants to know what a browser can make this package do reads this file
+ * and stops. See [the change spec's §Analytics dashboard → Local
+ * server](../../../.specs/changes/merged/2026-07-26-analytics_plugin.md).
+ *
+ * **Loopback, always.** The listener binds {@link LOOPBACK_ADDRESS} - a named
+ * constant, never `0.0.0.0` and never a wildcard - because the dashboard reads
+ * the Iceberg table over the *operator's own* AWS credentials
+ * (`adapters/duckdb-query.ts`). A wildcard bind would put an unauthenticated
+ * read of the site's traffic, signed as the operator, on every interface the
+ * machine has. The port is whatever the caller resolved from
+ * `config.analytics.dashboard.port` (task 44); this module reads no
+ * environment variable and states no port of its own, so
+ * `DEFAULT_DASHBOARD_PORT` keeps the single home task 44 gave it. Contrast
+ * the build agent (`packages/build-agent/src/server.ts`), which binds
+ * `0.0.0.0` from `process.env.PORT` - correct for a MicroVM behind a security
+ * group, wrong for a program holding an operator's session.
+ *
+ * **There is no route that accepts SQL, and that is structural rather than
+ * filtered.** The request surface is exactly two families:
+ *
+ *   - `GET {@link QUERY_ROUTE_PREFIX}<name>` - one of the seven names
+ *     `queries.ts` declares, resolved through that module's own
+ *     {@link queryDefinition} lookup, which is `Object.hasOwn`-guarded so
+ *     `constructor`, `toString` and `__proto__` are unknown names and not
+ *     inherited functions. An unknown name answers 404 listing the ones that
+ *     resolve.
+ *   - everything else - a static file from `appDir`, served only if it is on
+ *     the allow-list `FileSystem.listFiles(appDir)` returned.
+ *
+ * A caller therefore has nowhere to put a statement. The query string is
+ * checked against {@link QUERY_STRING_PARAMS} and an unrecognised key is
+ * *rejected*, not ignored, so `?sql=...` is a 400 and never a silently
+ * dropped parameter; the only methods answered are `GET` and `HEAD` - the two
+ * RFC 9110 §9.1 makes mandatory - and everything else is 405 naming them; and
+ * no handler in this module attaches a `data` listener to a request, so a
+ * request body is never a value this program holds. The type system says the
+ * same thing one layer down - `AnalyticsQuery.run` takes a `QueryName`, and
+ * `queries.ts` mints SQL only through a module-private tagged template - and
+ * this module is where that guarantee would have been thrown away, because
+ * here the compiler's knowledge of the name has already been erased to
+ * `string`.
+ *
+ * **Nothing this module holds is ever concatenated into a statement.** The
+ * date range and the bot-inclusion flag are parsed here, validated here
+ * through task 45's own {@link prepareQuery}, and handed to
+ * `AnalyticsQuery.run(name, params)` **unmodified**. The `PreparedQuery` that
+ * validation returns is used for exactly one field, its `name` - the
+ * `QueryName` the lookup just proved - and its `sql` is deliberately untouched:
+ * a statement is the adapter's business, and an edge module that held one
+ * would be one refactor away from letting a request shape it.
+ *
+ * **Loopback is not an origin, so the `Host` header is checked too.** Binding
+ * {@link LOOPBACK_ADDRESS} keeps other *machines* out; it does nothing about
+ * other *origins* in the operator's own browser. A page the operator visits
+ * can point a hostname it controls at 127.0.0.1 and fetch this server through
+ * that name - the DNS-rebinding shape - and because a browser judges
+ * same-origin by hostname, that page reads the responses. This module sends no
+ * CORS headers, and their absence is what refuses an ordinary cross-origin
+ * read; the rebinding case defeats that precisely by making the origin match,
+ * so no response header can answer it. What answers it is
+ * {@link ALLOWED_HOST_NAMES}: a request whose `Host` is not this listener's own
+ * address is refused with a 403 before anything else about it is read. The
+ * exposure that closes is bounded - the site's own traffic figures, nothing
+ * writable, no route that takes SQL - which is why it is three lines here
+ * rather than a design.
+ *
+ * {@link COMMON_HEADERS} carries `X-Content-Type-Options: nosniff` on every
+ * response for a neighbouring reason: `dist/app` is a build output whose file
+ * names this module does not choose, and an extension {@link CONTENT_TYPES}
+ * does not know is served as {@link DEFAULT_CONTENT_TYPE}, which a sniffing
+ * browser is otherwise free to re-read as something it will execute.
+ */
+import { type FileSystem } from 'blogwright-core';
+import type { AnalyticsConfig } from './config.js';
+import type { AnalyticsQuery } from './ports.js';
+/** What {@link createDashboardServer} is built from. */
+export interface DashboardServerOptions {
+    /**
+     * The port every route reaches the table through. The *only* surface this
+     * module touches below itself: `run(name, params)` and nothing wider, so
+     * there is no statement to supply and no write path to reach. The dashboard
+     * command constructs the DuckDB adapter and passes it here; a test passes
+     * the fixture-backed fake from `fixture-query.ts`.
+     */
+    readonly query: AnalyticsQuery;
+    /**
+     * The validated `analytics` block, taken for its `bots` mode alone - what
+     * {@link prepareQuery} needs to know whether an *absent* `includeBots`
+     * counts bot rows. Passing it, rather than picking a mode here, is what
+     * keeps the default in the one place task 44 put it.
+     */
+    readonly config: Pick<AnalyticsConfig, 'bots'>;
+    /**
+     * The port to bind, resolved from `config.analytics.dashboard.port`. Never
+     * a literal at the call site and never `process.env`: task 44 owns the
+     * default and its bounds.
+     */
+    readonly port: number;
+    /**
+     * The directory of prebuilt static files to serve - task 57's `dist/app`.
+     * Absent until that task lands, which is a 503 naming this directory rather
+     * than a stack trace.
+     */
+    readonly appDir: string;
+    /**
+     * How `appDir` is read. The `FileSystem` port, not `node:fs`: this package
+     * imports no filesystem builtin anywhere, so the listing and the reads go
+     * through the port the CLI already hands every plugin (`ctx.ports.fs`), and
+     * a test serves an application that never touched a disk.
+     */
+    readonly fs: FileSystem;
+}
+/**
+ * Where the listener actually ended up, read back off the socket rather than
+ * assumed. Not exported, following `ports.ts`' `QueryValue`: no consumer needs
+ * the type by name - one reaches it as `DashboardServer['address']` - and an
+ * export nothing names is what `pnpm knip` reports. Export it when a real
+ * consumer needs it by name.
+ */
+interface DashboardAddress {
+    /** The bound host. Always {@link LOOPBACK_ADDRESS}; asserted, not trusted. */
+    readonly host: string;
+    /** The bound port - the one that was asked for, since this server never binds port 0 itself. */
+    readonly port: number;
+}
+/** A running dashboard server. */
+export interface DashboardServer {
+    /** The address the listener is actually bound to. */
+    readonly address: DashboardAddress;
+    /** The URL to open, built from {@link address} rather than from the requested port. */
+    readonly url: string;
+    /**
+     * Stop listening and release the port. Resolves once the listener is closed
+     * and every open connection has been destroyed, so a caller that awaits it
+     * can bind the same port again immediately. Idempotent.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Start the dashboard's HTTP listener on {@link LOOPBACK_ADDRESS}. Resolves
+ * once the socket is bound, with the address read back off it, so a caller
+ * prints where the server *is* rather than where it was asked to be.
+ */
+export declare function createDashboardServer(opts: DashboardServerOptions): Promise<DashboardServer>;
+export {};