Repository navigation
v0.12.0
Pre-releasenpm install @setu-ts/kernel@0.12.0 @setu-ts/runtime@0.12.0Added
-
gRPC workspace example (
@setu-ts/cli, #570).apps/grpc-workspaceis what
setu new --workspaceandsetu generate appwrite, plus one gRPC call between members:
billing, generated with--rpc grpc, servesbilling.v1.BillingService/Quotefrom a.proto
in a workspace library, andorderscalls it with a Connect client at the address its generated
discovery map gives, answering400and503for billing's refusals and outages. A conformance
test regenerates the workspace and fails when the example drifts from the generator. The example
runs in the repository;setu new --example grpc-workspaceexplains that and points at
--workspaceand--rpc grpc. -
Durable agent runs (M136, #565,
@setu-ts/agent-runs-plugin,@setu-ts/common,
@setu-ts/database-plugin,@setu-ts/cli).AgentRunsPlugin,AgentRunsPluginOptions,
defineAgentRun,AgentRunDefinition,AgentRunContext,AgentRunToolCall,
AgentRunApprovalOptionsandVERSIONadd model-at-a-time persistence, fenced leases,
transactional tool idempotency, stored approval deadlines and UI-message replay. Common exports
CAPABILITIES.AGENT_RUNS,IAgentRunService,IAgentRunStore,AgentRunRow,
AgentRunEntryRow,AgentRunChunkBatch,AgentRunApprovalRow,AgentRunStatus,AgentRunJson,
AgentRunView,AgentRunSweepReport,AgentRunNotFoundError,AgentRunStateError,
AgentRunApprovalError,AgentRunDefinitionError,AgentRunLeaseLostErrorand
AgentRunStoreUnavailableError.createDatabaseAgentRunStore,DatabaseAgentRunStoreand
DatabaseAgentRunStoreOptionsbridge the application database.docs/durable-runs.mdcovers
recovery, Workers, outside-effect idempotency and workflow engines. Reading, streaming and
cancelling a run default to the principal that started it (canAccessreplaces the rule). Event
ids are<batch>.<index>.<epoch>; aLast-Event-IDthe stored log cannot honour gets a
data-setu-replaychunk and a full replay. A failed run is logged atwarnwith its error class
only. CLI agent briefs recognize the package and capability; manual installation only. Ships in
0.12.0. Tool timeouts recover through the sweep after lease expiry and fail withtool-timeout
aftertoolAttempts(default 3), replaying committed results or re-running rolled-back calls
(#566, #567). -
Changing a workspace's transport after scaffolding (M138, #568,
@setu-ts/cli).
setu workspace broker <name>changes the broker every member shares and
setu workspace rpc <member> <http|grpc>changes how one member is called. Each member now
carries a CLI-ownedsrc/transport/index.ts(messagingOptions(),queueOptions(),
transportPlugins(), andcsrfExclusions()on a full-stack member) that itssetu.config.ts
calls, so a change regenerates that module, the manifest, Compose, Kubernetes and the README's
<!-- setu:transport -->section, merges the packages it needs into each member, and never writes
the config. It refuses, writing nothing, when a config does not call the module (printing the
lines to add) or when source still uses what the change removes (--forcegoes ahead).
generate app,setu syncand, inside a member,setu add messaging|queue|grpcrender the
module through the same planner. -
Versioned
replaceSource(@setu-ts/common,@setu-ts/vector-store-plugin, #561).
replaceSource(collection, scope, sourceId, records, { version })refuses a write whose version
is older than the source's stored one with the newVectorVersionConflictError(409), so a late
queue retry of an older submission can no longer replace a newer one; an equal version is written
again.VectorReplaceOptionsis the options type andIVectorStoreAdapter.versionedReplacethe
opt-in an adapter declares to receive the version; the service refuses a version for any other
adapter withVectorOperationUnsupportedError. memory, pgvector (asource_versioncolumn read
under the source lock, added byensure: 'create'and required byensure: 'verify') and Qdrant
1.16+ (a conditionalupdate_filterupsert, soQdrantClientLikealso requirescountand
versionInfo) honour it; Vectorize already refusesreplaceSource.apps/semantic-search
versions each submission and drops a superseded job. -
The idempotency key in the OpenAPI document (
@setu-ts/common,@setu-ts/idempotency-plugin,
@setu-ts/openapi-plugin, #561). A route carryingidempotent()is documented with its key
header as a parameter, so Swagger UI can send it;RouteIdempotencyMetadatagains
required?: booleanso a route withrequired: falseis documented as optional. -
Tenant-scoped vector retrieval (M135, #558,
@setu-ts/common,@setu-ts/vector-store-plugin,
@setu-ts/cloudflare-plugin,@setu-ts/cli).CAPABILITIES.VECTOR_STOREandIVectorStore
add similarity search whose tenant scope is a required argument of every data method, never a
filter key.VectorStorePluginregisters the service underVectorStorePluginOptions;
IVectorStoreAdapteris the backend contract.MemoryVectorStore,PgVectorStore(Drizzle,
pgvector ≥ 0.8.0) andQdrantVectorStoreship in the package withMemoryVectorStoreOptions,
PgVectorDatabase,PgVectorExecutor,PgVectorStoreOptions,QdrantClientLike,
QdrantVectorStoreOptions,VectorStoreTenancyandVERSION.VectorizeVectorStore,
VectorizeIndexLike,VectorizeVectorLikeandVectorizeVectorStoreOptionsadd the Workers
adapter to cloudflare-plugin. Common addsVectorCollectionSpec,VectorRecord,VectorQuery,
VectorMatch,VectorFilter,VectorFieldType,VectorMetadataValue,vectorRecordKey,
VectorScopeRequiredError,VectorScopeInvalidError,VectorFilterError,
VectorDimensionError,VectorRecordError,VectorCollectionUnknownError,
VectorCollectionMismatchErrorandVectorOperationUnsupportedError.replaceSourcemakes
re-ingestion leave one copy; a filter is refused, never dropped; caller errors carry 400 status
hints and backend faults answer 503/504.setu add vector-storeinstalls the package and prints a
registration.apps/semantic-searchindexes queued documents and serves tenant-scoped search;
docs/retrieval.mdis the guide. Ships in 0.12.0.attachPoolErrorListenermoves from
database-plugin's internals to common, soPgVectorStoregives an app-owned node-postgres pool
the same'error'listener at startup and a dropped connection is reported instead of exiting the
process;IVectorStoreAdapter.opentakes the optional logger it reports through.toBackendFault
also classifies node-postgres's lost and timed-out connections, undici's socket and timeout codes,
andQdrantClientTimeoutError(503 before any statement is sent, 504 after). -
MCP example and website guide (
@setu-ts/cli, #554). Offersetu new --example mcp-tools
from 0.12.0, with scoped tools, idempotent retries, validation, rate limits, Origin checks and a
weighted archive quota. The standalone website guide includes the full scaffold-shaped application
and official-client tests.setu new --examplenow listsnpm run buildin its next steps when
an example starts from compiled output. -
Named route registration refusals (M131b, #557,
@setu-ts/common,@setu-ts/kernel,
@setu-ts/decorator-plugin).RouteRegistrationErrorcarries reason, method, path and cause;
decorated refusals name the controller and method. -
Client body-read errors (M131b, #557,
@setu-ts/runtime,@setu-ts/common,
@setu-ts/metrics-plugin).RequestBodyReadErrorcarries a fixed safe 400 hint and the native
cause. Logging keeps only its class and fixed detail; metrics labels the hinted status and counts
only 5xx as errors. Bun's native size refusal becomesRequestBodyTooLargeError/413, with an
optional cap and Infinity/generic detail for an unknown native bound. Bun answers that client
itself with an empty 413, so the mapped error reaches the handler, logs and metrics, not the
response body. -
Weighted quotas and AI SDK recipes (M134, #549,
@setu-ts/auth-plugin,
@setu-ts/telemetry-plugin).createQuota,IQuota,QuotaOptions,QuotaReservation,
IQuotaStore,MemoryQuotaStore,RedisQuotaStoreandIQuotaRedisClientadd atomic weighted
reserve/settle budgets with epoch or UTC calendar windows, issued receipts and expiry.
QuotaExceededError,QuotaStoreUnavailableErrorandrespondQuotaExceededexpose fail-closed
refusals. The rate limiter shares the quota body initializer with byte-identical output.
TelemetryPlugin.registerGlobaloptionally connects library spans to Setu's provider; refused
registration warns once and shutdown retains it. Library spans from a second app still use the
first app's exporter and service.name, and are dropped after that first app stops. Only its own
Setu spans stay private. Quota keys now reject ill-formed Unicode; both stores refuse unsafe
accumulated reservations even for unlimited keys. The refusal constructor validates policy names
and retry seconds. RedisQuotaStore requires a client-owned command bound; it never times out calls
itself. Use iorediscommandTimeout: 15_000or common'sfromNodeRediswith its default
15-second bound; unbounded clients can hold every request on stalled Redis. The AI guide and Node
apps/ai-chatdemonstrate SDK tool loops, structured output, streaming, fallback, capture-off
tracing and outbox/inbox usage delivery. AI dependencies stay in the application and root
development tooling. No Setu AI package is introduced; existing applications need no changes.
Ships in 0.12.0. -
Typed client command (M129, #547,
@setu-ts/cli,@setu-ts/common,
@setu-ts/openapi-plugin).setu clientboots without a port or reads JSON with
--input <file|url>, generatessrc/clientsdk/api.tswith the project's own SDK, and writes a
marked managed file.--checkis a read-only drift gate;--dry-runreports the write plan.
--output,--factory,--type-name,--dirand--configselect paths and names.
setu add sdkadds opt-inclientandclient:checkscripts without replacing existing ones.
IOpenApiServicemoves to common and remains re-exported by openapi-plugin; its shape is
unchanged. See the CLI guide for bootstrap effects, input bounds and write refusals. -
MCP route tools (M133, #545, #552,
@setu-ts/mcp-plugin,@setu-ts/common,@setu-ts/kernel,
@setu-ts/auth-plugin,@setu-ts/idempotency-plugin,@setu-ts/decorator-plugin,
@setu-ts/cli).McpPlugin,McpPluginOptions,McpToolDeclaration,
McpPluginConfigurationErrorandVERSIONexpose explicitly declared routes through a stateless
SDK endpoint. Caller-filtered lists use private cache hints; calls re-enter guards, validation,
tenancy, rate limits, idempotency and audit.timeoutMsbounds each call (default 30000 ms, safe
integer 1–600000): the runtime deadline aborts the inner request and races dispatch/result
reading, cancelling the response reader and returningThe tool timed out.. Functional
mcpTool()and method-only@McpTool()mark routes for discovery;toolsis now optional.
Common'sMCP_TOOL_METADATA,RouteMcpToolMetadata,withMcpToolMetadataand
mcpToolMetadataOfshare the marker across both styles. Names are 1–64 characters; every marked
or listed route must declare security intent, and ambiguous or empty tool sets refuse startup.
Idempotency-branded tools require an authenticating security brand; the brand'skeyHeadernames
the header the route reads its key from, the derived key is sent there, and a route keyed by a
body field or a function refuses startup.allowedOriginsmust list every browser UI origin,
including same-origin UIs. Common adds optionalIApplication.dispatchandDispatchOptions,
implemented by the kernel with IP, abort and streaming support.DispatchOptions.routepins the
registered route pattern before route middleware runs.IDEMPOTENCY_METADATA,
RouteIdempotencyMetadata,withIdempotencyMetadataandidempotencyMetadataOfdescribe both
HTTP idempotency entry points.REQUIRED_SCOPES_STATE_KEYmoves to common without changing its
value.setu add mcpinstalls the optional@modelcontextprotocol/server@^2.4.0peer. Existing
applications need no changes; seedocs/upgrading.mdfor opt-in tool safety and replay behavior. -
Full-stack kernel modules and
getService(M130, #551,@setu-ts/cli,@setu-ts/common,
@setu-ts/react-router-plugin,@setu-ts/full-stack-starter). Common addsserviceToken,
ServiceToken,requestService,RequestBoundService,resolveRequestServiceand
RequestServiceUnavailableError: a request-bound service is built once per request and token from
the kernel request context and shared by every caller in that request. The React Router plugin
addsgetService(context, token),serviceResolverContext,ServiceResolverand
ServiceResolverUnavailableError; the load context holds a resolver closure, never the kernel
request context. The full-stack template now keeps business logic insrc/modules/<name>/(the
productsmodule, its/api/productsroutes and a request-bound service) and pages inapp/
(routes,components,lib, server-onlyserver), reached through the~kernel/*alias.
setu g modulein a full-stack project writes a token, a request-bound service,/api/<name>
routes and tests that sign a session and send its CSRF token;--pageadds a guarded page and is
refused where a page already exists.setu checkrefuses a value import of kernel code from
app/(setu.E017) and reports a page it cannot parse or read safely, including one a symlink
places outsideapp/(setu.E018). The generatedentry.server.tsxexportshandleError, which
ignores aborted requests and 404s and logs other errors once through the logger. The full-stack
starter keeps page, asset and Vite proxy routes out of OpenAPI, merged with the application's
lists. The template pinslucide-react1.67.0, binds the Vite HMR socket toVITE_PORTon every
runtime, and emits the Cloudflare Workers README section only for Workers. -
A registry of real tenants (M127, #548,
@setu-ts/multi-tenancy-plugin,@setu-ts/common,
@setu-ts/database-plugin).MultiTenancyPlugintakestenants— a list, anITenantRegistry
(new incommon) or aRegistryFactory— and checks every resolved id before the request carries
it: an unknown id answersunknownTenantStatus(default404,Unknown Tenant), a registry
fault answers503(Tenant Registry Unavailable), and no response byte names the id (the fault
warning logs no registry message text, only error names and codes). The registry's tenant replaces
the resolved one, so its canonical id reaches the session binding and cache prefix. Ids over 256
characters never reach the registry. With or withouttenants, a non-string or empty id — from a
custom resolver or alookupTenantpayload — is refused (404), never admitted as tenant''.
Instance and factory registries are cached (tenantCache: canonical hits only, TTL 30 s on the
monotonic clock, 1 000 entries, 1 MiB, single-flight;TenantRegistryCacheOptions).
IMultiTenancyService.lookupTenant(id)runs the same check for queue and message handlers and
throwsTenantRegistryUnavailableError(503 status hint) on a fault.
createDatabaseTenantRegistry(options?: DatabaseTenantRegistryOptions)indatabase-pluginreads
tenants from rows, withactiveFieldfor suspension and onlyid,nameand an explicit
toMetadataon the tenant. The health indicator reportsregistry.apps/multi-tenantlists
acmeandglobex. -
Backend faults answer
503or504(M131a, #543,@setu-ts/common,@setu-ts/queue-plugin,
@setu-ts/messaging-plugin,@setu-ts/realtime-backplane-plugin).commonexports
BackendUnavailableError(503, "The request was not applied."),BackendOutcomeUnknownError
(504, "The backend did not answer; the request may have been applied."), theBackendFault
union andtoBackendFault(error, source). Only a refusal before any send (a refused or
unresolvable connection, a closed or offline client, ioredis with its offline queue off) answers
503; a lost connection (MaxRetriesPerRequestError, "Connection is closed.", a reset) or an
expired bound (Command timed out) always answers504, because ioredis rejects commands already
sent with these errors and both drivers write a queued command as soon as a socket opens. Three
security-audit rounds each found a window where a "not sent" decision built on driver events was
false, so none is attempted.watchConnectionattaches the connection-error reporter and detaches
it on stop (returning aConnectionWatch).QueueService.add, the Redis Streamspublishand
the realtime backplane's Redispublishwrap a recognised driver failure in one of them, keeping
the driver error ascause; it is never served.PublishTimeoutErrorkeeps its name and gains
the504hint itself (X88-5). -
setu addRedis arms for every Redis-backed plugin (M131a, #543,@setu-ts/cli).
setu add cache --store redis,setu add idempotency --store redis,
setu add scheduler --lock redisandsetu add realtime-backplane --backplane rediswire the
plugin's Redis arm onREDIS_URLthrough the project's Redis client: node-redis when the
configuration imports the generatednodeRedisClienthelper, ioredis when the project depends on
ioredis, otherwise the--redis-clientgiven (ioredis by default). A--redis-clientthat
disagrees with the client already in use is refused (X88-1). -
An OpenTelemetry preload in every generated Node project (M131a, #543,
@setu-ts/cli). Node
scaffolds carryinstrumentation.mjs, which registers OpenTelemetry's ESM loader hook, and run it
with--import ./instrumentation.mjsfromstart,start:dev,start:debugand the production
image'sCMD, so the drivers the plugins import lazily are instrumented. Without
@opentelemetry/instrumentationinstalled it does nothing.setu add telemetrynow also installs
the OTLP exporter and, on Node,@opentelemetry/instrumentationand the instrumentation for the
project's Redis client, and prints theinstrumentationskey that enables it. The telemetry
README documents the preload for hand-written projects (X88-4, X88-10). -
maskUrlUserinfo(M131a, #543,@setu-ts/common). Masks URL userinfo in a string; the
default redaction rule below, exported for text that never passes through a redaction service
(X88-8). -
Resource-server authentication (M132, #541, #552,
@setu-ts/auth-plugin,@setu-ts/common,
@setu-ts/openapi-plugin).IPrincipalgainsscopes(from the OAuth 2.0scope/scp
claims,scopewinning when both are present) andactor(anIPrincipalActor,
{ id, claims }, from the outermost RFC 8693act), andRouteSecurityMetadatagainsscopes.
requireScopes(first, ...rest)is an ALL-of guard:401anonymous,403
insufficient-privilegeswhen any scope is missing, with the required list in the challenge; each
scope is a build-time-validated RFC 6749scope-tokenand a duplicate is refused.
requireAuth({ delegation })refuses ('forbid') or requires ('require') a delegated token,
andRefreshTokenServicewrites a delegated principal's actor into theactclaim, and its OAuth
scopes into thescopeclaim, of the tokens it mints, so the exchange keeps both. A bearer
strategy (jwtorissuers) orresourceServermakes every401answer
WWW-Authenticate: Bearer(witherror="invalid_token"for a Bearer-carrying request) and every
scope403answerBearer error="insufficient_scope", scope="…"; nothing from the request is
echoed.resourceServer(ResourceServerOptions) serves an RFC 9728 protected-resource document
derived from configuration at/.well-known/oauth-protected-resourceplus the resource's path,
and adds itsresource_metadataURL to both challenges.TrustedIssuer.audienceaccepts a list
(any match) andrequireAccessTokenTypeopts into the RFC 9068at+jwtheader type
(typ-mismatch). Derived OpenAPI security requirements now carry the sorted, unique scopes of a
route'srequireScopesguards; a declaredsecuritystill wins. These are OAuth scopes, not
M110b's scoped grants. -
Optimistic locking (M128, #540,
@setu-ts/database-plugin,@setu-ts/common,
@setu-ts/multi-tenancy-plugin).updateVersioned(repo, id, expectedVersion, data, options?)
anddeleteVersioned(repo, id, expectedVersion, options?)write only while the record still
carries the expected version, setting it toexpectedVersion + 1, and throw the new
VersionConflictError(409) orEntityNotFoundError(404) on a miss. They accept any
repository withupdateWhere/deleteWhereandfindById— outer, unit-of-work and tenant
repositories alike — and refuse before any I/O on an invalid version, a payload that sets the
version field, or a repository without conditional writes (conditional-write,501). Their
parameter types areVersionedWritable,VersionedDeletableandVersionedWriteOptions.
ITenantDataStoreandITenantRepositorygain optionalupdateWhere/deleteWhere, implemented
byDatabaseTenantDataStore(one precondition with the tenant column, no check-then-write
fallback),MemoryTenantDataStoreand the multi-tenancy plugin's repository.
Changed
-
BREAKING — the workspace transport is split into a broker and a per-member RPC style (M138,
#568,@setu-ts/cli).setu new --workspace --transportand--transport-urlare removed and
refused with a pointer to their replacements:--broker <name>and--broker-url <url>on the
workspace (memoryis the default;http/grpcare not brokers), and
setu generate app <name> --rpc grpcper member. A gRPC member can now sit in a workspace with a
real broker, which onetransportfield could not express.setu.workspace.jsonis version 2
(broker,brokerUrl, per-memberrpc); a version-1 manifest is still read and is written back
as version 2, and a 0.11.0 CLI refuses a version-2 file rather than misreading it. A gRPC member's
proto/README.mdis now wrapped the waydeno fmtwants. -
Atomic header batches (M131b, #557,
@setu-ts/common,@setu-ts/kernel).setHeaders
validates every entry before writing any, preserving prior headers on refusal and caching frozen
errors. -
Cleanup after the handler (M131b, #557,
@setu-ts/common,@setu-ts/kernel,
@setu-ts/di-plugin). An early middleware response returns immediately while request cleanup
and shutdown drain retain the running handler; scopes are not disposed under it. -
Typed-token documentation (M131b, #557,
@setu-ts/common,@setu-ts/di-plugin).
createToken<T>carries compile-time inference only; T is erased and tsx/start:dev does not
type-check. Use tsc through generated check/build scripts. -
Session-stamp revocation (M131b, #557,
@setu-ts/auth-plugin). A definite mismatch deletes
the HTTP auth record and regenerates its session; a reader fault suspends one request and
preserves the record. Revocation takes effect when the old cookie is next presented, including on
a request that throws (the session plugin deletes the superseded store row before rethrowing). A
stamp must only move forward: restoring an old value revives cookies not yet presented, and copied
encrypted-cookie sessions; read-only fromHeaders callers stay suspension-only, as does an auth
middleware given a custom priority that runs before the session middleware. -
Model component names (M131b, #557,
@setu-ts/openapi-plugin,@setu-ts/sdk). Hoisted
schemas use their Zod id or their site plus schema path, with roots reserved before descendants;
an id is never given a name another operation's root uses, and an id outside the OpenAPI
component-name grammar ([A-Za-z0-9._-]) is ignored in favour of the site name, with ids
containing/or~now resolving instead of leaving a dangling$ref. Nullable primitives stay
inline. Regenerated clients can rename component types. -
BREAKING for implementors:
IMultiTenancyServicegains the requiredlookupTenant(M127, #548,
@setu-ts/common). Applications that only consume the service are unaffected; an out-of-tree
implementation must addlookupTenant(id): Promise<Option<ITenant>>or delegate to
MultiTenancyService. -
Notification is out of readiness by default (M131a, #543,
@setu-ts/notification-plugin). The
notificationindicator registers with{ readiness: false }, asmailalready is (M119b):
every channel addresses a dependency all replicas share, so/readyno longer fails while a
channel is down;/healthstill reports it. Restore the old behaviour with
HealthPlugin({ readiness: { include: ['notification'] } })(V11-11). -
Enqueue and publish failures answer
503/504instead of a masked500(M131a, #543). See
Added; a client that retried only on503should treat504as "outcome unknown" and retry only
with an idempotency key (X88-5). -
Redaction masks URL userinfo by default (M131a, #543,
@setu-ts/common). Every string value
no redaction pattern matches hasscheme://user:password@hostrewritten toscheme://***@host,
in what a redaction service sees: log metadata by default (the logger builds one with its secure
default paths), and trace attributes and audit records only when the telemetry or audit plugin is
given a redaction policy, since neither redacts without one. A log MESSAGE string is not redacted;
describeError, which renders the error text in the framework's own connection-error lines and
the generated start line, masks URL userinfo itself before its 8192-character bound (X88-8). -
Generated start scripts load
.env, and a failed boot prints one masked line (M131a, #543,
@setu-ts/cli). Node local scripts pass--env-file-if-exists=.env(aftertsx watch, which
reads its subcommand first) and Deno's pass--env-file=.envwhere the project writes one; Bun
loads.envitself; images keep the platform environment. The generatedmain.tscatches a
failed boot, printsStartup failed: …throughdescribeErrorandmaskUrlUserinfo, and exits
1, so a malformedREDIS_URLno longer reaches stderr with its password (X88-2, X88-8). -
describeErrormasks URL userinfo (M131a, #543,@setu-ts/common). Every name, message and
classifier value is masked before the 8192-character bound, so a cut cannot expose part of a
password (security audit). -
Plugins report an injected client's connection errors (M131a, #543). The cache, idempotency,
queue, scheduler, realtime-backplane, messaging and auth rate-limit Redis stores now attach their
connection-error reporter to an injected client as well as a built one, so a node-redis outage
logs onewarnper plugin per state change; the listeners are removed again when the plugin stops
(watchConnection).fromNodeRedisrejects its firstconnect()at once on the first connection
error, naming the cause, instead of after the 15 s command bound (X88-3). -
Redis Streams polls outside any request (M131a, #543,
@setu-ts/messaging-plugin). The broker
starts one poll timer and one reclaim timer atconnect()for all subscriptions instead of one
pair persubscribe(), so a handler that subscribes lazily no longer parents every poll span to
that request (X88-7). -
Queue loop failures report once per state change (M131a, #543,
@setu-ts/queue-plugin). A
recurring-scheduling or depth-probe failure logs onewarnwhen it starts and oneinfoon
recovery instead of anerroron every poll (X88-9). -
Breaking: a token with a malformed
actclaim is refused (M132, #541,
@setu-ts/auth-plugin). A JWT-strategy or trusted-issuer token whoseactis present but is
not an object with a non-emptysuborclient_idwas accepted before and is now refused (401;
the issuer reason isact-malformed). An absentactis unaffected. The migration steps are in
docs/upgrading.md, 0.12.0, "Resource-server authentication (M132,@setu-ts/auth-plugin,
@setu-ts/common)". -
Bearer challenges on 401s and scope 403s (M132, #541,
@setu-ts/auth-plugin). An application
with a bearer strategy (jwtorissuers) orresourceServernow sends
WWW-Authenticate: Bearer …on a401and on a scope403. The header is additive, but a test
that asserted its absence must be updated. -
Breaking: the rate limiter emits draft-11 header fields and refuses options it used to accept
(#539,@setu-ts/auth-plugin,@setu-ts/common,@setu-ts/exceptions). Each item below is
breaking, and none has an option that restores the old behaviour. The migration steps are in
docs/upgrading.md, 0.12.0, "Rate limiter now emits draft-11RateLimitfields".rateLimitMiddlewareemits theRateLimitandRateLimit-PolicyStructured Field Lists of
draft-ietf-httpapi-ratelimit-headers-11 instead ofRateLimit-Limit,RateLimit-Remainingand
RateLimit-Reset. A client that read the old fields, or a CORSexposedHeaderslist naming
them, must read the new two instead. The newpolicyNameoption (default'default') names the
policy in both fields and in the 429'sviolated-policies.- The factory now throws at registration where it used to accept the value:
windowMsmust be a
positive integer number of milliseconds (round a fractional value; RedisPEXPIRErefused one
afterINCRhad created the key, leaving a counter that never reset),maxan integer from 0
to 999999999999999, andpolicyNamenon-empty printable ASCII. - Under the Problem Details formats (
rfc9457,rfc7807) the 429 body'stypeandtitle
change from the status-derived values (about:blankandToo Many Requestsunder RFC 9457) to
https://iana.org/assignments/http-problem-types#quota-exceededandQuota Exceeded, with a
violated-policiesmember. A client matching the oldtypemust match the new one. The
defaultformat's body is unchanged. Retry-Afterandtare clamped to 0…999999999999999 (the RFC 9651 sf-integer range). A store
reporting a reset that had already passed produced a negativeRetry-After; it is now0.- A store result whose
countis not a non-negative whole number, or whoseresetTimeis not
finite, answers 429 for a full window (fail closed); it used to be served. Fix the store.
Added alongside:
ErrorResponseInit.problemand theProblemTypeInitinterface, honoured by both
Problem Details formatters and by status hints and ignored by thedefaultformat; and
RedisRateLimitStorere-arms a key it finds without an expiry instead of answering 429 for ever.
Fixed
-
A workspace's dev runner gives up on a prerequisite that never answers
/ready(#570,
@setu-ts/cli). The generatedscripts/dev.mjsandscripts/dev.tsprobed/readywith no
bound, so a prerequisite that accepted the connection and never responded held the runner for
fetch's own 300-second header timeout instead of its 30-second deadline. Each probe now times out
after one second, and the runner names the stalled service at the deadline. -
Generated READMEs link the site, and the example-download refusal works from
npm create
(X93-7, X93-3, M131d, #564,@setu-ts/cli). A scaffolded project's and a workspace's README
linkhttps://setu-ts.dev/instead of GitHub, which some readers cannot reach. When
setu new --examplecannot download a file, the refusal suggests
npx @setu-ts/cli new <name> --template <t>, which works from bothsetuand
npm create @setu-ts, and names the nested socket error and itscode(ENOTFOUND,
ECONNREFUSED) instead of only "fetch failed". -
setu add authon a full-stack project links the password sign-in recipe (X89-3, M131d, #564,
@setu-ts/cli). The starter-arm note also prints the auth-plugin README's full-stack recipe,
since the template's own login is a placeholder.--styleon the full-stack template is refused
as functional-only rather than as having no controller seam, which it has (X91-8). -
graphql-demoworks outside the repository (X93-1, M131d, #564). The example declaresws,
the runtime's optional WebSocket peer, so a downloaded copy's WebSocket transport no longer closes
with 1006; its smoke now completes agraphql-transport-wshandshake. -
Release link definitions (X93-4, M131d, #564). CHANGELOG gains its missing
[0.11.0]
definition and compares[unreleased]fromv0.11.0.release:bumpnow writes the new version's
definition and moves the[unreleased]base, andrelease:verifyrefuses a version heading
without a definition or a stale[unreleased]base. The website's link check also checks a
fragment on another page, which is how the changelog's/#versioninglinks shipped broken
(X93-5); the versioning policy is now thedocs/versioning.mdpage. -
Documentation that did not match the code (M131d, #564). The upgrade guide covers the #526
controllers break for 0.11.0 (X90-1), re-runningsetu agentsafter an upgrade (V11-18), the
Workers full-stack repair's@types/nodeandwaitUntilsteps (V10-16), when a missing Deno
import-map entry fails (V11-16, also in the openapi README) and what an existing project does for
M131c.docs/deployment.mdleads with deploying a scaffolded project throughsetu build,
corrects "a standalone project emits no Dockerfile", and walks through an authenticated registry
withsetu workspace deploy --pull-secret(X93-2, X87-5);docs/cli.mddocuments
setu workspace buildanddeployand the E014–E016 findings (X91-8); the collector fan-out page
carries its config inline (X93-2). The auth-plugin README shows password sign-in in the full-stack
template and the CSRF token for its JSON login (X89-3); the logger README lists every request
record (V11-17);CsrfFormOptions.headerNameno longer says multipart bodies go unparsed (V11-2);
optional peers in a workspace and the telemetry README's peer list are corrected (V10-50); Getting
Started namessetu add(X93-9); example READMEs drop repository-only text and the rest-api
README says how to change the port (X93-6). -
Cross-site WebSocket handshakes are refused (#562,
@setu-ts/websocket-plugin,
@setu-ts/kernel,@setu-ts/common). Security. A page on another site could open any WebSocket
route, GraphQL's included, with the user's cookies: a handshake is aGET, so the CSRF middleware
never saw it.WebSocketPluginnow answers403to a handshake whoseOriginis neither the
app's public origin nor in the newallowedOriginsoption, before route guards and before a
connection slot; a client with noOriginis admitted, andcheckOrigin: falseturns the check
off. The kernel passes the proxy-aware public origin asrouteUpgrade's new optional third
argument. Migration: list a browser front end served from another origin (a separate SPA host,
a dev server on its own port) inallowedOrigins; behind a TLS-terminating proxy, trust it with
HttpSecurityPlugin({ ipSecurity: { trustProxy: true, trustedProxies } })or list the public
origin, since the request URL is otherwisehttp://and everyhttps://page is refused. See
docs/upgrading.md. -
IGraphqlService.executewith a request context and no method runs a mutation only forPOST
(#562,@setu-ts/graphql-plugin). Security. An application route forwarding a request to
execute(params, ctx)let a cross-siteGETrun a mutation; the method is now derived from the
request and fails closed, the rulesubscribealready applied. An explicit method still wins. -
Workspace development ports (X87-2, M131c, #560,
@setu-ts/cli). Full-stack members read
their application and Vite ports from discovery, withvitePortallocated in
setu.workspace.json. Standalone defaults remain unchanged; member READMEs name the manifest as
the port source. -
Member inspector ports (X87-6, M131c, #560,
@setu-ts/cli). Members recordinspectPort;
optionaldevBasePortcontrols the development range. All allocators skip every recorded port.
Adoption and reallocation rewrite one exact inspector token and explain scripts they leave
unchanged. -
Deno tooling isolation (X87-4, M131c, #560,
@setu-ts/cli). Generated and printed npm-tool
commands use--no-lock; runtime images also remove the@setu-ts/testingimport-map pin. -
Authenticated image pulls (X87-5, M131c, #560,
@setu-ts/cli). Repeatable
workspace deploy --pull-secretvalidates the names and checks, before building, that each Secret
exists with an image-pull type (reading only its type), then attaches them to each member's pod.
Dry runs perform the checks and list the names. A repeatable flag given once without a value
(--pull-secret,--depends-on,--build-arg) is refused, not replaced by a later value. -
Workspace OTLP pin coverage (V10-50 remainder, M131c, #560,
@setu-ts/cli). A member
telemetry-add regression test verifies the exporter dependency is recorded at the workspace root. -
Workers config guidance (V11-3, M131c, #560,
@setu-ts/cli). Generated comments name Node
through tsx as the CLI config loader, whose import handling refusescloudflare:workers. -
Workers local-variable ignore (V11-4, M131c, #560,
@setu-ts/cli). Every Workers project
ignores.dev.vars, including projects that do not emit a local variables file. -
Agent verification commands (V11-9, M131c, #560,
@setu-ts/cli). Briefs include available
lint and formatting scripts, Deno's native checks, and a rule to run the verification commands
before done. After upgrading, runsetu agentsand commit the rewritten briefs:
setu agents --checkreports every brief written by an older CLI as stale. -
Fresh-scaffold card guidance (X93-8, M131c, #560,
@setu-ts/cli).new --agents, including
examples, prints one install-and-check hint in place of per-card warnings before the first
installation. -
Config wiring uses (X91-3, M131c, #560,
@setu-ts/cli). Imports alone no longer satisfy
config wiring;registerModulesmust be called. Barrels report E003 when an imported route
registrar is absent from their registration code. -
Located config warnings (V11-8, M131c, #560,
@setu-ts/cli). One W001 names the unsupported
construct, line and affected symbols, and can be silenced atsetu.config.ts. -
Plain service listings (X93-10, M131c, #560,
@setu-ts/cli). A service missing its
describe<Name>convenience export reports W005 instead of a registration error. -
Same-named controller adoption (X91-1, M131c, #560,
@setu-ts/cli). The first module can
adopt its own controller and optional service, omitting generated CRUD tests. Service-only and
full-stack same-named adoption explain why they are refused, as does a same-named file
setu checkskips; a nested controller of the same name still counts as a name conflict. -
Hoisted page checks (X87-1, M131c, #560,
@setu-ts/cli). Generation finds React Router's
binary up to the workspace root while keeping the member as its working directory. -
Shadowed plugin commands (V11-15, M131c, #560,
@setu-ts/cli).setu commandsomits plugin
names reserved by built-ins and warns once per name. -
Symlink remedy (V10-27 remainder, M131c, #560,
@setu-ts/cli). A symlinked member's refusal
asks only to replace the link with its directory. -
Page shadowing documentation (X91-4, M131c, #560,
@setu-ts/cli). The CLI guide explains that
a kernel route answers document requests when it shares a page's path. -
Cross-site requests cannot run a GraphQL mutation (#559,
@setu-ts/graphql-plugin). Security.
BothPOST /graphqlandPOST /graphql/streamnow require thecontent-typemedia type to equal
application/json(parameters ignored) and answer anything else, a missing header included,415
without reading the body. The HTTP route had accepted any header merely containing
application/json(text/plain; x=application/json), and the SSE route checked nothing — both
CORS simple requests a page on another site can send with no preflight.GET /graphql/streamnow
refuses a mutation405withAllow: POST, asGET /graphqlalready did: it had run it, and a
cross-site top-level navigation is aGETthat carriesSameSite=Laxcookies. Both SSE refusals
are answered before any stream opens. -
Caller errors from a GraphQL resolver keep their meaning (#559,
@setu-ts/graphql-plugin,
@setu-ts/exceptions). A resolver that throws a 4xxHttpError(notFound(),forbidden(),
…) or an error branded withwithHttpStatusHintis answered on HTTP, SSE and WebSocket with the
hint'sdetailand anextensions.code(NOT_FOUND,FORBIDDEN,UNAUTHENTICATED, …) instead
ofInternal server error; a 5xx stays masked. To make that possible a 4xxHttpErrornow
carries thecommonstatus hint, so two other readers see it: an app with noerrorHandler
answers a thrown 4xxHttpErrorwith its status instead of an opaque500, and the
resource-server Bearer challenge addsWWW-Authenticateto a thrownunauthorized(). -
Unhandled errors reported without a logger mask URL userinfo (#559,
@setu-ts/kernel). With
noCAPABILITIES.LOGGERregistered, the kernel reports an unhandled request error straight to
runtime.reportError(stderr), where no LoggerPlugin redaction runs, and wrote
scheme://user:password@hostin the message, stack and causes as thrown. That record now gets the
same URL-userinfo mask LoggerPlugin anderrorHandlerapply; which fields are logged is
unchanged. -
A regenerated session's old row is deleted even when the request throws (M131b, #557,
@setu-ts/session-plugin).regenerate()is a revocation, so the session middleware deletes
the superseded store row before rethrowing a request's error (a store fault there is logged at
warn). A sign-in or second-factor step that regenerates and then throws now also loses the
pre-login stored session, such as an anonymous cart; the user starts sign-in again. -
Node startup bind failures (M131b, #557,
@setu-ts/runtime,@setu-ts/common). The default
Node host waits for binding and rejects with the native error; injected hosts share that
obligation. -
Devtool startup reporting (M131b, #557,
@setu-ts/cli). The generated entry catches
creation/start failures, prints connector-start guidance and exits 1. -
Node start without a build (M131b, #557,
@setu-ts/cli). The start script checks dist/main.js
and names the build script before launch; generated fixtures are recaptured. -
Unhandled client hints (M131b, #557,
@setu-ts/kernel,@setu-ts/common,
@setu-ts/logger-plugin,@setu-ts/metrics-plugin). WithouterrorHandler, a 4xx-hinted
failure is served with its hinted status, title and detail, aserrorHandlerwould, and logged at
warn; unhinted errors and 5xx hints keep the opaque 500. The newfallbackErrorStatusin
@setu-ts/commonis that rule, and request logging and HTTP metrics label a thrown error with the
status actually served (responder?.statusFor?.(error) ?? fallbackErrorStatus(error)), so metrics
also stop counting a thrownHttpErrorundererrorHandleras 500.fallbackErrorHintreturns
the served hint itself, read once, so the kernel's status, title and detail come from one
snapshot. -
Trusted diagnostics sockets (M131b, #557,
@setu-ts/runtime). At the 32-socket cap, idle
untrusted sockets are evicted before trusted ones; only sent authenticated success responses
establish trust. -
Devtool usage (M131b, #557,
@setu-ts/cli). Both usage strings name setu devtool enable. -
Whole-graph boot findings (M131b, #557,
@setu-ts/di-plugin,@setu-ts/decorator-plugin). A
controller cannot stop validation at its own subgraph; aliases and repeated findings are
deduplicated. -
Retry policy validation (M131b, #557,
@setu-ts/resilience-plugin). Invalid attempt counts or
delays throw RangeError at registration/wrap time, including a delay longer than a runtime timer
can wait (2^31 - 1 ms, which Node, Deno and Bun clamp to 1 ms); a computed exponential backoff is
capped there. A limit of 1 executes once. -
Kafka first-join replay (M131b, #557,
@setu-ts/messaging-plugin). The consumer skips its
already delivered partition window after a first-join rewind, while delivering earlier historical
offsets. -
Full-stack form posts (M131b, #557,
@setu-ts/full-stack-starter,
@setu-ts/react-router-plugin,@setu-ts/http-security-plugin). With React Router configured,
both starter entry points default referrerPolicy to same-origin and preserve explicit or
disabled-header choices. -
View document doctype (M131b, #557,
@setu-ts/cli,@setu-ts/view-plugin). The generated
layout emits a doctype; renderView and @Render continue sending engine output unchanged. -
setu new --exampledownloads the examples as they now stand (#553,@setu-ts/cli). The
repository examples were brought back to the CLI scaffold's structure, withapps/full-stackon
the M130 module layout, and the offered file lists forcqrs,di-decorators,graphql-demoand
grpcwere regenerated to match. -
setu checkreads a configuration that usesenv['KEY'](@setu-ts/cli, #554). Any computed
member access madesetu.config.tsunclassifiable, sosetu checkwarned that every barrel was
unwired even when the configuration wired them all. Member access by one plain string naming an
ordinary property, such ascreateRuntimeServices().env['JWT_SECRET'], now classifies like
env.JWT_SECRET. Names such asconstructor,prototypeand__proto__, concatenated or
variable keys, and a computed key directly after{or,are still refused. -
setu checkand the CLI's configuration edits refuse the legacy accessor methods
(@setu-ts/cli, #554).__defineGetter__,__defineSetter__,__lookupGetter__and
__lookupSetter__now makesetu.config.tsunclassifiable, likeObjectandReflect:
({}).__lookupGetter__('__proto__')reaches a prototype through a string argument the lexer
cannot see into. -
The error handler masks URL credentials in what it logs and serves (M130 audit, #551,
@setu-ts/exceptions).errorHandlerlogged an error's message unmasked, so a driver error
such asconnect failed: postgres://u:pw@db/xput the password in the log line while the same
record's cause was masked by the logger's redaction. The message, and the serialized cause, now
pass throughmaskUrlUserinfobefore they reach the logger, and the runtime error sink used when
no logger is registered masks the message, stack and cause the same way. The response body is
masked too: a thrownHttpError's served message, details and stack (underincludeStackTrace),
4xx and 5xx alike, a custom formatter's output, andrespondWithErrorbodies now serve
postgres://***@db/x, keeping the host. Arespondhook's own result is not masked. -
Swagger UI after
setu add openapi(M129, #547,@setu-ts/cli). Node, Deno and Bun now
install the exactswagger-ui-distrelease that the Swagger UI integrity hashes match; without
it, an application using the default self-hosted assets could not boot. Workers receives no
additional dependency. -
kernel: a streamed response whose source emits zero-length chunks without pause no longer
exhausts the heap. The Node adapter's writer reads the next chunk as soon as a write reports no
backpressure, which an empty chunk always does, so such a source starved the event loop until the
process aborted (over plain HTTP as well as MCP). Every streamed body now drops empty chunks and
waits a runtime timer turn after each one (M133 audit; #545). -
queue-plugin: a stopped Redis reads
downon the queue indicator again. The Redis adapter's
probe answersfalsewithout I/O when the client's ownstatussays it lost its connection
(reconnecting,close,end), andfromNodeRedisreportsreconnectingonce a ready client
drops; before, ioredis parked the ping in its offline queue and the indicator readupwith
reachable: 'unknown', the0.11.0regression. A paused Redis still readsup/unknown
(V11-10, M131a; #543). -
cli: the
REDIS_URLcommentsetu new --broker/setu addwrites into.envsays what reads
the value: the local start scripts, while a deployment sets the variable in its own environment. -
messaging-plugin docs:
publishTimeoutMs: 0removes only the plugin's bound; an injected
node-redis client still appliesfromNodeRedis'scommandTimeoutMs(default 15 s), and the
README says how to raise it (X88-6, M131a; #543). -
auth-plugin: a
jwt.schemeconfigured with capitals (for example'Token') no longer refuses
every token: the JWT strategy compared the lowercased request scheme with the configured value as
written. The scheme is now matched case-insensitively (M132; #541). -
database-plugin: a connection lost while a Drizzle × PostgreSQL transaction was open no longer
exits the process. pg-pool leaves a checked-out client without an'error'listener, so a
terminated backend raised an unhandled'error'event; every checked-out client now gets one
(logged atwarn), and the transaction answers503(X94-1, M128; #540). -
database-plugin: outage-time driver errors that answered a masked
500are classified, each
measured on the real engine: node-postgres57P01and "not queryable" →503, "Connection
terminated unexpectedly" →504; PrismaP1001,P2028and the driver code under
P2039/P2010(57P01; mariadb45028,45013,1053→503,45009→504); mysql2
ER_SERVER_SHUTDOWN→503,PROTOCOL_CONNECTION_LOST→504; libsqlSQLITE_BUSY→503;
MongoDBMongoWaitQueueTimeoutError,MongoPoolClearedErrorandNotWritablePrimary→503
(X94-2, M128; #540). -
database-plugin:
IDatabaseService.transaction()no longer classifies an error its own work
throws, so a refused HTTP call inside an inbox handler is reported as itself rather than as
DatabaseUnavailableError. Repository calls inside the work are still classified (V11-5, M128;
#540). -
database-plugin, multi-tenancy-plugin: a refused conditional-write precondition or payload
(UnsupportedQueryFeatureErrorwith feature'write-precondition': an empty or non-scalar
where, an invalid expected version, a payload that sets the version field, a tenant-scoped
precondition naming the tenant column) answers400 Bad Requestwith the fixed detail "The write
precondition or its payload is invalid." instead of a masked500logged at error level.
MemoryTenantDataStore's refusals reject rather than throwing synchronously, and both tenant
stores refuse an empty precondition (M128 security audit; #540). -
database-plugin:
getRepository()returns one repository per entity instead of rebuilding its
data source and wrapper on every call, the cost behind the measured point-read gap (X94-3, M128;
#540). -
cli:
setu add messaging --broker <arm>andsetu add queue --queue <arm>on an existing
standalone project now append the connection variable (for exampleREDIS_URL) to the project's
dotenv file with its local default and to the tracked.exampleempty, the rows
setu new --brokerwrites. A file that already assigns the variable, set or commented out, is
left alone, so a re-add writes nothing; a dotenv file the project does not have is named instead
of created. The file is theenvFilePathsetu.config.tsdeclares, read past comments and string
contents (the last entry of an array); a configuration that declares none, or names it in a form
the CLI cannot read, gets a message instead of a write to.env. Previously both files were left
without the variable and the hint printed as an unlabelled line.docs/cli.mdalso no longer says
addinstalls the client: it records it in the manifest (X91-9, V11-14; #537).
Releases before v0.1.0-alpha.8 shipped as tags only; their notes live in
CHANGELOG.md.