Skip to content

docs(compute,async,observability): correct 11 block READMEs, add errors tables, move Compute options - #1640

Draft
xyos wants to merge 13 commits into
aws:mainfrom
xyos:docs/readme-runtime-blocks
Draft

xyos wants to merge 13 commits into
aws:mainfrom
xyos:docs/readme-runtime-blocks

Conversation

@xyos

@xyos xyos commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

The READMEs of 11 blocks (2,506 lines, 17,933 words) contained statements the source contradicts, spread one fact over several sections, and had 16 prose lines longer than 400 characters (bb-realtime 8, bb-async-job 7, bb-logger 1).

  • bb-cron-job said enabled: false disables a job "until manually triggered". No manual trigger exists.
  • bb-tracer said a Tracer with enabled: false has zero X-Ray cost. One enabled Tracer anywhere in the app turns X-Ray on for every compute.
  • The Compute option defaults, image rules and synth errors were only in the READMEs of bb-container-compute and bb-lambda-compute, packages an app does not import.
  • The bb-logger retention example was not valid TypeScript and replaced the sandbox preset with the production one.

Issue #, if available:

Changes

bb-compute. Takes over the option tables per type (with defaults and logRetention), ## Errors (synth failures and warnings), ## Scaling and ## Container image. scaling.strategy is documented as signal objects (packages/core/src/common/compute-capabilities.ts:84-87), and one table gives the default strategy for the three cases in packages/bb-container-compute/src/index.cdk.ts:661-675. strictNamespacePlacement is explained once and says older native clients and raw callers are refused (packages/core/src/cdk/blocks-defaults.ts:320-324).

bb-container-compute, bb-lambda-compute. Options, scaling, image rules, errors, installation and when-to-use are links to bb-compute. Each keeps its class members, provisioned resources and package-specific facts. The bb-lambda-compute link to the Compute README is relative, not to main.

bb-email-client. API moves ahead of the security section (rules unchanged; the counter-example is removed). ## Errors is a table from src/errors.ts:22-28 and names the packages that export isBlocksError and EmailErrors. "Package Export Conditions" did not match package.json:29-40 and is removed.

bb-async-job. Corrections: DLQ name is {fullId}-dlq (src/index.cdk.ts:148); local retries are immediate and an exhausted job is logged (src/index.mock.ts:318-330); the AWS retry wait is stated (src/index.cdk.ts:160). Errors table adds InvalidOption (src/errors.ts:27).

bb-cron-job. Corrections: enabled: false deploys a DISABLED schedule with no manual trigger (src/index.cdk.ts:118, src/index.mock.ts:98-102); the mock rejects L, W, # with ScheduleNotSupported and ignores the year field (src/schedule.ts:74-75,92-93,190); the mock does not retry (src/index.mock.ts:182-187). New "Delivery and retries" table replaces four sections that repeated it.

bb-realtime. Corrections: four methods, not three; revokeAccess is runtime-only (src/index.cdk.ts:195); PublishFailed cause (src/index.aws.ts:125,148); onDisconnect('error') repeats per failed attempt and refresh times out at 15 s (src/aws-middleware.ts:47,60,313-316); npm run test:e2e:sandbox is not a template script. Errors and options tables added; access rules follow the API.

bb-dashboard. Corrections: metrics takes { metrics, metricConfigs? } (src/types.ts:95-108); dashboardName defaults to the block's fullId (src/index.cdk.ts:75; id in a deployed function, src/index.aws.ts:53); traces need an enabled Tracer (packages/bb-tracer/src/index.cdk.ts:25-30); deploy with npm run sandbox or npm run deploy. Adds MetricsSource and errors tables.

bb-logger. Retention example is const defaults = { ...(sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production), logRetention }. "Log level filtering without code changes" is removed (no LOG_LEVEL in src).

bb-metrics. namespace defaults to the block's fullId (src/index.aws.ts:101-103); InvalidNamespace is thrown at runtime, not at synth (src/index.aws.ts:105, src/index.cdk.ts:35-41).

bb-tracer. enabled row and cost list corrected (src/index.cdk.ts:25-30); the mock samples by samplingRate and throws RangeError outside 0 to 1 (src/index.mock.ts:109-112).

bb-logger, bb-metrics and bb-tracer cross-references say Logger and Tracer, not Logging and Tracing.

A follow-up commit regenerates the bb-compute row of the block catalog in packages/blocks/README.md (npm run sync-docs), because the README's first sentence changed.

File (packages/…/README.md) Lines Words Lines over 400 chars
bb-async-job 270 → 228 2573 → 2085 7 → 0
bb-compute 233 → 303 1920 → 2210 0 → 0
bb-container-compute 203 → 88 1435 → 610 0 → 0
bb-cron-job 311 → 179 1878 → 1373 0 → 0
bb-dashboard 252 → 175 1488 → 1128 0 → 0
bb-email-client 295 → 238 1886 → 1636 0 → 0
bb-lambda-compute 71 → 71 574 → 506 0 → 0
bb-logger 163 → 138 747 → 682 1 → 0
bb-metrics 185 → 147 1045 → 823 0 → 0
bb-realtime 414 → 354 3668 → 3043 8 → 0
bb-tracer 109 → 95 719 → 601 0 → 0
Total 2506 → 2016 17933 → 14697 16 → 0

Look hardest at:

  • bb-compute now holds the option defaults, scaling rules and error list that existed only in the bb-container-compute and bb-lambda-compute READMEs, and bb-container-compute shrinks to links (203 → 88 lines).
  • The corrected bb-cron-job statements: no manual trigger for enabled: false, and which cron expressions the local mock rejects.
  • The errors sections added across the group: each "thrown when" cell against its throw site.

Not changed on purpose:

  • Examples keep the import specifiers they had (@aws-blocks/bb-*, @aws-blocks/core) and the npm install lines stay. Whether block READMEs should import from @aws-blocks/blocks is a separate decision.
  • Source comments the READMEs now disagree with: the JSDoc of CronJobErrors.ScheduleNotSupported (packages/bb-cron-job/src/errors.ts:13, a year field) and of CronJob (src/index.mock.ts:36, manual trigger); the npx cdk deploy hint printed by the bb-dashboard mock (src/index.mock.ts:77).

Open questions:

  • bb-compute documents the warning id @aws-blocks/bb-container-compute:api-rule-quota, which names a package apps do not import. Rename or accept?
  • bb-async-job: the Lambda retry wait is derived from the source, not observed on a deployed stack.
  • bb-realtime: an unknown namespace throws InvalidNamespace, which has no RealtimeErrors constant. Add one?
  • bb-dashboard: the runtime defaults dashboardName to id, the construct to fullId. Align the source?
  • bb-tracer: only the local mock range-checks samplingRate.
  • bb-logger: whether Lambda sets _X_AMZN_TRACE_ID when no Tracer is enabled is not settled by the source.
  • bb-email-client: "1 email per second" in the SES sandbox is an SES quota, not checked by this package.

Related pull requests: none superseded. Open pull requests that touch the same files; whichever merges second rebases:

Part of a set of README revisions: #1635 (core), #1636 (hosting and pipeline), #1637 (bb-agent and bb-knowledge-base), #1638 (bb-auth and auth-common), #1639 (the storage blocks), #1641 (the guide, the scaffolder and its templates), #1642 (the native SDKs), #1643 (contributor docs). Each merges on its own.

Validation

Run on this branch alone at 7d9021f0d, on main 8940cfd2f, with Node 22. All pass:

  • npm run build
  • the shipped-docs tests in packages/blocks (readme-links, docs-pointers, doc-snippets, imports-reference)
  • packages/blocks sandbox-dir-coverage (no tracked file names the old directory .blocks-sandbox)
  • packages/core readme-policies (the IAM policy JSON)
  • packages/bb-auth readme-recipes, first-admin, multi-block-snippets, users-cli, gate-diagnostics
  • packages/auth-common ui.react-types
  • packages/bb-kv-store readme.generated (every README snippet compiled) and legacy/runtime
  • packages/create-blocks-app npm test
  • npm run sync-docs:check
  • npm run check:imports
  • changeset-guard.ts validate-structure
  • changeset-guard.ts verify-coverage
  • changeset-guard.ts verify-umbrella
  • changeset-guard.ts block-major
  • every relative link and #anchor in the changed files, and every link into them from another Markdown file, resolves (checked with a script)

Run once on all the README branches of this set combined, as they were on an earlier main commit (e1e484465), and not run again after the rebases: packages/core unit suite, packages/blocks unit suite, packages/bb-kv-store unit suite, packages/bb-auth unit suite, packages/auth-common unit suite, npm run lint, npm run lint:deps and npm run check:api. All passed.

Not run locally: the full npm test across all workspaces, npm run test:e2e:local and the sandbox e2e suites. CI runs them.

No test was added: the tests listed above already read these READMEs, and the remaining statements are checked against the source by review.

Checklist

  • PR description included
  • Tests are changed or added
  • Relevant documentation is changed or added (and PR referenced)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 8ed74a1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 13 packages
Name Type
@aws-blocks/bb-compute Patch
@aws-blocks/bb-container-compute Patch
@aws-blocks/bb-lambda-compute Patch
@aws-blocks/bb-email-client Patch
@aws-blocks/bb-async-job Patch
@aws-blocks/bb-cron-job Patch
@aws-blocks/bb-realtime Patch
@aws-blocks/bb-dashboard Patch
@aws-blocks/bb-logger Patch
@aws-blocks/bb-metrics Patch
@aws-blocks/bb-tracer Patch
@aws-blocks/blocks Patch
@aws-blocks/create-blocks-app Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

xyos added 13 commits November 19, 2026 05:47
…th errors in one README

The README described `scaling.strategy` as "one or more of `cpu`/`memory`/`queue-depth`"; it is one signal object or an array of them (`{ on: 'cpu', targetPercent }`, `{ on: 'memory', targetPercent }`, `{ on: 'queue-depth', backlogPerInstance }`), and the default strategy was described differently in two places.
One table now states the default strategy for the three cases: jobs only, no jobs, jobs and an `ApiNamespace`.
Option defaults, the container image rules and the synth errors were only in the `bb-container-compute` and `bb-lambda-compute` READMEs; this README now has an options table per type (including `logRetention`), and `## Errors`, `## Scaling` and `## Container image` sections.
`## API namespaces` explains `strictNamespacePlacement` once instead of three times and keeps the statement that a raw HTTP caller or an older native client is refused once the option is on.
The first sentence names both compute types and the service behind each; the line about provisional type names and planned `vm` and `kubernetes` types is removed.
…, scaling, image rules, errors

The README repeated the options table, scaling rules, image rules, error list, installation, quick start and when-to-use sections of the `Compute` block.
Those sections are replaced by links to the `bb-compute` README, which now holds them.
A `## Container image and boot` list keeps the facts specific to this package: the esbuild bundle and bootstrap, `DEFAULT_CONTAINER_IMAGE`, the container user, the working and boot directories and the ports.
Headings are `## API`, `### Options`, `## Errors`, `## What it provisions (AWS)`, `## Local development` and `## See also`.
…only the architecture row

The README linked the `Compute` README on the `main` branch, which does not match an installed version; the link is now relative.
The options table keeps `architecture`, the one option `Compute` does not expose, and links to the `bb-compute` README for the others.
`## Local development` states that in local dev handlers run in-process and `memory` and `maxTimeoutSeconds` have no effect.
…re the security section

The "Package Export Conditions" section showed an `exports` map that did not match `package.json`; the section is removed.
`## Errors` is a table of constant, `error.name` and cause, replacing a try/catch whose facts were in comments, and says which packages export `isBlocksError` and `EmailErrors`.
The constructor options (now with a Default column and the `logger` option), `send()`, `sendBatch()` and input validation come directly after the quick start; one `EmailMessage` field table serves both methods.
The security section follows the API with the same rules, and a callout under the title links to it; the open-relay counter-example is removed.
`## Limits` is removed: each limit is stated in "Input validation", `sendBatch()` or `## Scaling and cost (AWS)`.
…name and local retry behaviour

The README named the dead-letter queue `{scope}-{id}-dlq`; it is `{fullId}-dlq`.
It said retries and dead-letter behaviour are enforced locally as on AWS; locally a failed delivery is retried immediately and an exhausted job is logged, not queued.
`## Errors` is a table (constant, `error.name`, thrown when) and lists `AsyncJobErrors.InvalidOption`, which was missing.
`## What it provisions (AWS)` states how long a failed delivery waits before its retry: `900 + maxBatchingWindowSeconds` seconds on a Lambda compute, about 2 minutes on a container compute.
The method lists are one `## API` table, the options table has a Type column and the `batchSize` and `maxBatchingWindowSeconds` ranges, and the `submitBatch` rules and the timeout rules of `trackStatus` are lists under their own headings.
"Compute Compatibility" and "Other options" are removed; their facts are in the `compute` option row, the errors table and `## What it provisions (AWS)`.
…cheduleNotSupported

The README said `enabled: false` disables a job "until manually triggered" and titled an example "Manual-Only in Dev"; there is no manual trigger, and the `enabled` row now says the schedule is deployed in the `DISABLED` state and does not fire on AWS or locally.
`## Errors` is a table and lists `CronJobErrors.ScheduleNotSupported`, which the local mock throws for a cron expression that uses `L`, `W` or `#` in a day field.
`## Local development` states that the mock ignores the year field of a cron expression and does not retry a failed handler.
`InvalidSchedule` and `InvalidTimezone` are documented as thrown at construction locally and at synth time on deploy.
A `## Delivery and retries` table states delivery path and retry count per compute type; the "Quick Reference", "Compute Compatibility", "Best Practices" and "Key Distinction from AsyncJob" sections, which repeated those facts, are removed.
…e API, delivery guarantees

The README said the instance "exposes three methods" above a four-row table and omitted `revokeAccess` from the runtime-only list; both are corrected.
`PublishFailed` was described as "publish fan-out failed"; it is thrown when the callback URL or the connections table is unavailable, and a failed delivery to one connection is logged.
The `refresh` rules state the 15-second timeout and that `onDisconnect('error')` fires once per failed reconnect attempt (up to 5) and once more when the client gives up.
The reference to `npm run test:e2e:sandbox`, a script no template defines, is removed, and the intro latency figure for 1,000 subscribers is "about 100–200 ms", as in the cost section.
`## Errors` is a table, `## API` has the constructor signature and an options table, the channel-name and access rules follow the API with one rule per list item, and `## Delivery guarantees` collects the delivery rules that were under "Best Practices".
The per-subscriber cost and latency tables are replaced by the formula and one sentence, and the recommended (not enforced) channel-name limits are removed.
…ction rules; one options table

An example passed a `Metrics` block as the `metrics` option, which takes `{ metrics, metricConfigs? }`; it is removed and a `### MetricsSource` table documents the shape.
The `dashboardName` default was given as `scope.fullId`; it is the block's own `fullId`, and in a deployed function the property falls back to `id`.
The widget table no longer says all widgets are always included: the traces section exists only when the app has an enabled `Tracer`.
`## Local development` says the mock creates no dashboard (`url` is `null`, the route returns 503) and names `npm run sandbox` and `npm run deploy` instead of `npx cdk deploy`.
`## Errors` is a table that states when `InvalidMetricConfig` is thrown (an empty `name` or a `period` below 1, during CDK synthesis), and the three option tables are one with defaults.
…t; options table

The retention example was a bare `defaults: { ...BlocksPresets.production, ... };` statement, which is not valid TypeScript and drops the sandbox preset; it is now a `const defaults = ...` statement that keeps the `sandboxMode` preset choice, with the file and call it belongs to named above it.
The intro promised "log level filtering without code changes" while a later section said there is no `LOG_LEVEL` variable; the claim is removed and the `level` row says the option is the only way to set the level.
The cross-reference named a `Tracing` block; the class is `Tracer`.
Options are a table with defaults, the `defaultContext` row lists the reserved keys, one sentence says what the `traceId` key of an entry is, and the `awsRequestId` paragraph is a four-item list.
`## Log Level Precedence` and `## Error Object Handling` are removed; the options table and the serialization list cover them.
…ere each error is thrown

The `namespace` default was given as `scope.fullId`; it is the block's own `fullId`.
`InvalidNamespace` was described as "too long, contains invalid characters"; the row gives the 256-character limit and the allowed characters and says it is thrown by `new Metrics(...)` at runtime and in local dev, not during CDK synthesis.
The cross-references named `Logging` and `Tracing` blocks; the classes are `Logger` and `Tracer`.
`## Errors` is a top-level section whose table has an `error.name` column and the method that throws, and `## Quick start` comes before `## API`.
`## Synchronous API Rationale` is one line under the method table, and two examples that repeated the `EmitOptions` table are removed.
…her Tracer is enabled

The README said `enabled: false` means zero X-Ray cost; a disabled `Tracer` only removes its own opt-in, and X-Ray stays on for every compute while any other `Tracer` is enabled.
The `enabled` row states this and what the methods do when disabled (`startSegment` still runs the function, `getTraceId()` returns `null`).
`## Local development` no longer says the mock records all traces: it samples by `samplingRate`, and the `samplingRate` row says the mock throws `RangeError` for a value outside 0 to 1.
The types link to `./src/types.ts` is replaced by `npm run docs:api Tracer`, the cross-reference names `Logger` instead of `Logging`, and the `## Sampling` section is merged into the option rows.
The first sentence of the bb-compute README changed; `npm run sync-docs` copies it into the catalog table.
@xyos
xyos force-pushed the docs/readme-runtime-blocks branch from 3902e8f to 7d9021f Compare November 19, 2026 06:11

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant