Repository navigation
docs(compute,async,observability): correct 11 block READMEs, add errors tables, move Compute options - #1640
Draft
xyos wants to merge 13 commits into
Draft
docs(compute,async,observability): correct 11 block READMEs, add errors tables, move Compute options#1640xyos wants to merge 13 commits into
xyos wants to merge 13 commits into
Conversation
🦋 Changeset detectedLatest commit: 8ed74a1 The changes in this PR will be included in the next version bump. This PR includes changesets to release 13 packages
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 |
This was referenced Nov 18, 2026
xyos
force-pushed
the
docs/readme-runtime-blocks
branch
from
November 18, 2026 21:38
8ed74a1 to
3902e8f
Compare
…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
force-pushed
the
docs/readme-runtime-blocks
branch
from
November 19, 2026 06:11
3902e8f to
7d9021f
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-realtime8,bb-async-job7,bb-logger1).bb-cron-jobsaidenabled: falsedisables a job "until manually triggered". No manual trigger exists.bb-tracersaid aTracerwithenabled: falsehas zero X-Ray cost. One enabledTraceranywhere in the app turns X-Ray on for every compute.Computeoption defaults, image rules and synth errors were only in the READMEs ofbb-container-computeandbb-lambda-compute, packages an app does not import.bb-loggerretention 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 andlogRetention),## Errors(synth failures and warnings),## Scalingand## Container image.scaling.strategyis documented as signal objects (packages/core/src/common/compute-capabilities.ts:84-87), and one table gives the default strategy for the three cases inpackages/bb-container-compute/src/index.cdk.ts:661-675.strictNamespacePlacementis 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 tobb-compute. Each keeps its class members, provisioned resources and package-specific facts. Thebb-lambda-computelink to theComputeREADME is relative, not tomain.bb-email-client. API moves ahead of the security section (rules unchanged; the counter-example is removed).## Errorsis a table fromsrc/errors.ts:22-28and names the packages that exportisBlocksErrorandEmailErrors. "Package Export Conditions" did not matchpackage.json:29-40and 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 addsInvalidOption(src/errors.ts:27).bb-cron-job. Corrections:enabled: falsedeploys aDISABLEDschedule with no manual trigger (src/index.cdk.ts:118,src/index.mock.ts:98-102); the mock rejectsL,W,#withScheduleNotSupportedand 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;revokeAccessis runtime-only (src/index.cdk.ts:195);PublishFailedcause (src/index.aws.ts:125,148);onDisconnect('error')repeats per failed attempt andrefreshtimes out at 15 s (src/aws-middleware.ts:47,60,313-316);npm run test:e2e:sandboxis not a template script. Errors and options tables added; access rules follow the API.bb-dashboard. Corrections:metricstakes{ metrics, metricConfigs? }(src/types.ts:95-108);dashboardNamedefaults to the block'sfullId(src/index.cdk.ts:75;idin a deployed function,src/index.aws.ts:53); traces need an enabledTracer(packages/bb-tracer/src/index.cdk.ts:25-30); deploy withnpm run sandboxornpm run deploy. AddsMetricsSourceand errors tables.bb-logger. Retention example isconst defaults = { ...(sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production), logRetention }. "Log level filtering without code changes" is removed (noLOG_LEVELinsrc).bb-metrics.namespacedefaults to the block'sfullId(src/index.aws.ts:101-103);InvalidNamespaceis thrown at runtime, not at synth (src/index.aws.ts:105,src/index.cdk.ts:35-41).bb-tracer.enabledrow and cost list corrected (src/index.cdk.ts:25-30); the mock samples bysamplingRateand throwsRangeErroroutside 0 to 1 (src/index.mock.ts:109-112).bb-logger,bb-metricsandbb-tracercross-references sayLoggerandTracer, notLoggingandTracing.A follow-up commit regenerates the
bb-computerow of the block catalog inpackages/blocks/README.md(npm run sync-docs), because the README's first sentence changed.packages/…/README.md)bb-async-jobbb-computebb-container-computebb-cron-jobbb-dashboardbb-email-clientbb-lambda-computebb-loggerbb-metricsbb-realtimebb-tracerLook hardest at:
bb-computenow holds the option defaults, scaling rules and error list that existed only in thebb-container-computeandbb-lambda-computeREADMEs, andbb-container-computeshrinks to links (203 → 88 lines).bb-cron-jobstatements: no manual trigger forenabled: false, and which cron expressions the local mock rejects.Not changed on purpose:
@aws-blocks/bb-*,@aws-blocks/core) and thenpm installlines stay. Whether block READMEs should import from@aws-blocks/blocksis a separate decision.CronJobErrors.ScheduleNotSupported(packages/bb-cron-job/src/errors.ts:13, a year field) and ofCronJob(src/index.mock.ts:36, manual trigger); thenpx cdk deployhint printed by thebb-dashboardmock (src/index.mock.ts:77).Open questions:
bb-computedocuments 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 throwsInvalidNamespace, which has noRealtimeErrorsconstant. Add one?bb-dashboard: the runtime defaultsdashboardNametoid, the construct tofullId. Align the source?bb-tracer: only the local mock range-checkssamplingRate.bb-logger: whether Lambda sets_X_AMZN_TRACE_IDwhen noTraceris 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:
bb-dashboard,bb-logger,bb-metrics,bb-tracerREADMEspackages/bb-metrics/README.mdpackages/bb-async-job/README.mdpackages/bb-dashboard/README.mdpackages/bb-cron-job/README.mdpackages/bb-logger/README.md__proto__response keys in Realtime and FileBucket client middleware #1313, fix(bb-realtime): confirm a subscribe once publish() can find it #1364:packages/bb-realtime/README.mdpackages/bb-email-client/README.mdPart 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, onmain8940cfd2f, with Node 22. All pass:npm run buildpackages/blocks(readme-links,docs-pointers,doc-snippets,imports-reference)packages/blockssandbox-dir-coverage(no tracked file names the old directory.blocks-sandbox)packages/corereadme-policies(the IAM policy JSON)packages/bb-authreadme-recipes,first-admin,multi-block-snippets,users-cli,gate-diagnosticspackages/auth-commonui.react-typespackages/bb-kv-storereadme.generated(every README snippet compiled) andlegacy/runtimepackages/create-blocks-appnpm testnpm run sync-docs:checknpm run check:importschangeset-guard.ts validate-structurechangeset-guard.ts verify-coveragechangeset-guard.ts verify-umbrellachangeset-guard.ts block-major#anchorin 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
maincommit (e1e484465), and not run again after the rebases:packages/coreunit suite,packages/blocksunit suite,packages/bb-kv-storeunit suite,packages/bb-authunit suite,packages/auth-commonunit suite,npm run lint,npm run lint:depsandnpm run check:api. All passed.Not run locally: the full
npm testacross all workspaces,npm run test:e2e:localand 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
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.