@shivaedev/server 0.35.1 → 0.37.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.md +26 -14
- package/dist/AppModule.d.ts +3 -2
- package/dist/AppModule.d.ts.map +1 -1
- package/dist/adapters/migrationsIn.d.ts +5 -0
- package/dist/adapters/migrationsIn.d.ts.map +1 -0
- package/dist/adapters/migrationsIn.js +10 -0
- package/dist/adapters/migrationsIn.js.map +1 -0
- package/dist/appDatabaseHttp.d.ts +76 -68
- package/dist/appDatabaseHttp.d.ts.map +1 -1
- package/dist/appHost.d.ts +38 -34
- package/dist/appHost.d.ts.map +1 -1
- package/dist/appHostHttp.d.ts +38 -34
- package/dist/appHostHttp.d.ts.map +1 -1
- package/dist/appHostHttp.js +6 -7
- package/dist/appHostHttp.js.map +1 -1
- package/dist/appModules.d.ts +4 -3
- package/dist/appModules.d.ts.map +1 -1
- package/dist/appModules.js +7 -4
- package/dist/appModules.js.map +1 -1
- package/dist/hostRpc.d.ts +5 -1
- package/dist/hostRpc.d.ts.map +1 -1
- package/dist/hostRpcRoutes.d.ts +5 -1
- package/dist/hostRpcRoutes.d.ts.map +1 -1
- package/dist/hostSensitiveKeys.d.ts +10 -2
- package/dist/hostSensitiveKeys.d.ts.map +1 -1
- package/dist/hostSensitiveKeys.js +31 -5
- package/dist/hostSensitiveKeys.js.map +1 -1
- package/dist/redactedHost.d.ts +11 -0
- package/dist/redactedHost.d.ts.map +1 -0
- package/dist/redactedHost.js +11 -0
- package/dist/redactedHost.js.map +1 -0
- package/dist/workerHost.d.ts +6 -2
- package/dist/workerHost.d.ts.map +1 -1
- package/dist/workerHost.js +5 -2
- package/dist/workerHost.js.map +1 -1
- package/package.json +29 -29
- package/src/AppModule.ts +4 -3
- package/src/adapters/migrationsIn.ts +12 -0
- package/src/appHostHttp.ts +29 -32
- package/src/appModules.ts +14 -7
- package/src/hostSensitiveKeys.ts +35 -5
- package/src/redactedHost.ts +26 -0
- package/src/workerHost.ts +17 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,31 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.37.0 - 2026-11-20
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- `migrationsIn(directory)` from `@shivaedev/server/adapters/migrationsIn.ts` returns an `AppModule` `migrations` value whose loader reads the `migrations` folder in `directory` with `MigratorFileSystem.fromFileSystem` under `NodeServices.layer`, so a registration writes `migrations: migrationsIn(import.meta.dirname)`. It needs the optional peer `@effect/platform-node`.
|
|
8
|
+
- `AppModule.migrations` is optional. A module without migrations leaves it out, and `appModules` combines the loaders and schema components of the modules that declare them.
|
|
9
|
+
- `workerHost` masks its logs, the causes its installed error reporters receive and its exported spans with the application host's policy: the built-in credential-shaped name rules, `config.sensitiveKeys`, and the names of fields that the models of the repositories it builds mark sensitive (`sensitive: true` or a Redacted schema). Its `config` takes `sensitiveKeys` beside the database settings, typed as the new `WorkerHostConfig`. A worker serves no RPC group, so no RPC schema adds names.
|
|
10
|
+
- `workerHost` logs `Worker ready to take jobs` once its workers are registered, inside its redaction and trace export.
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- Require Effect 4.1.4 and its matching platform packages.
|
|
15
|
+
- closing `appDatabase`, and interrupting a host that waits for migrations, end the pool's connections without waiting for PostgreSQL's disconnect acknowledgements.
|
|
16
|
+
- `appModules` names a defined module by its own name in `DuplicateModuleQueue`.
|
|
17
|
+
|
|
18
|
+
### Breaking
|
|
19
|
+
|
|
20
|
+
- A registration with `module:` no longer accepts `name`: the module already carries its name, and a second one could disagree with it. Delete the `name` line from each `module:` registration. A `group` plus `handlers` registration still requires `name`.
|
|
21
|
+
- `workerHost` exports traces through `otlpTracing` itself, as `appHost` does, so the export masks the worker's whole policy, and its Layer's error type now includes `SensitiveFieldConflict` and `InvalidRedactionMask`. Remove `Layer.provide(otlpTracing)` from around `workerHost`; keeping it builds a second exporter and diagnostics pipeline around the worker. Remove an application's own readiness log around `workerHost` too, such as `Layer.tap(() => Effect.logInfo("Worker ready to take jobs"))`: the host now writes it, and an effect composed around the host's Layer runs outside its redaction and exporter.
|
|
22
|
+
|
|
23
|
+
## 0.36.0 - 2026-11-19
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
|
|
27
|
+
- `appHost` masks the names of fields that a repository model marks sensitive (`sensitive: true` or a Redacted schema), and their encoded names, in every RPC's logs, error reports, failure frames and exported traces, as it masks `config.sensitiveKeys`. The policy is complete before the host serves its first request, so mark a sensitive value once, on the server's model.
|
|
28
|
+
|
|
3
29
|
## 0.35.1 - 2026-11-18
|
|
4
30
|
|
|
5
31
|
### Changed
|
package/README.md
CHANGED
|
@@ -84,7 +84,7 @@ Host option types include this HTTP-only shape. A wrapper that reads native RPC
|
|
|
84
84
|
|
|
85
85
|
`appHost` is the server entry point for an Effect app. For a PostgreSQL app, supply the native RPC group, handler and service Layers, migration loader, session policy and static asset directory. The host completes migrations before acquiring application services, starts Node HTTP with native Effect RPC over a WebSocket upgrade at `/rpc`, and provides SQL, Reactivity and `LiveServer` from `@shivaedev/contract/live-server/service.ts` to those Layers.
|
|
86
86
|
|
|
87
|
-
For feature modules, install the optional peer `@shivaedev/admin` and declare each registration with `satisfies AppModule` from `@shivaedev/server/AppModule.ts`. Each module supplies
|
|
87
|
+
For feature modules, install the optional peer `@shivaedev/admin` and declare each registration with `satisfies AppModule` from `@shivaedev/server/AppModule.ts`. Each module supplies its operations, `services` and, when it owns tables, `migrations: { loader, components? }`; a module without migrations leaves the field out. A defined module takes its name from the module itself and its registration gives none, so the two cannot disagree; a `group` plus `handlers` registration supplies a `name`, because nothing else names it. `migrationsIn(directory)` from `@shivaedev/server/adapters/migrationsIn.ts` returns `{ loader }` for the `migrations` folder in `directory`, read with Effect's `MigratorFileSystem.fromFileSystem` under Node's `NodeServices.layer`, so a registration writes `migrations: migrationsIn(import.meta.dirname)` and needs the optional peer `@effect/platform-node`. Register caller-dependent Layers in the optional `requestServices` slot beside global `services`. Keep default adapters in its optional `ports` Layer, put an optional `registerAdmin` result in `admin`, and declare owned `queues` and a `workers` Layer on the module. `jobModule` from `@shivaedev/jobs/server/jobModule.ts` supplies those two fields from a jobs registration list.
|
|
88
88
|
|
|
89
89
|
```ts
|
|
90
90
|
import { Effect } from "effect";
|
|
@@ -102,24 +102,24 @@ const hosts = Effect.gen(function* () {
|
|
|
102
102
|
});
|
|
103
103
|
```
|
|
104
104
|
|
|
105
|
-
A module defined with `defineModule` from `@shivaedev/contract/defineModule.ts` registers as `module:`, and the host builds its group and its handlers with `moduleHandlers`. Its `services` provide what the module's `requires` lists, except the SQL client and the other services the host provides.
|
|
105
|
+
A module defined with `defineModule` from `@shivaedev/contract/defineModule.ts` registers as `module:`, and the host builds its group and its handlers with `moduleHandlers`. Its `services` provide what the module's `requires` lists, except the SQL client and the other services the host provides. An RPC group that is not a defined module, such as a contract served by hand-written handlers, registers as `group` plus `handlers` instead, and both kinds sit in one application's module list:
|
|
106
106
|
|
|
107
107
|
```ts
|
|
108
108
|
import { Layer } from "effect";
|
|
109
|
-
import {
|
|
109
|
+
import { SqlClient } from "effect/sql";
|
|
110
110
|
import { defineModule } from "@shivaedev/contract/defineModule.ts";
|
|
111
|
+
import { migrationsIn } from "@shivaedev/server/adapters/migrationsIn.ts";
|
|
111
112
|
import type { AppModule } from "@shivaedev/server/AppModule.ts";
|
|
112
113
|
import { Create, Get } from "./notes/operations.ts";
|
|
113
114
|
import { Drafts, readDraft } from "./drafts.ts";
|
|
114
115
|
|
|
115
116
|
export const Notes = defineModule({ name: "notes", operations: [Create, Get], requires: [SqlClient.SqlClient] });
|
|
116
117
|
|
|
117
|
-
export const notes = { migrations:
|
|
118
|
+
export const notes = { migrations: migrationsIn(import.meta.dirname), module: Notes, services: Layer.empty } satisfies AppModule;
|
|
118
119
|
|
|
119
120
|
export const drafts = {
|
|
120
121
|
group: Drafts,
|
|
121
122
|
handlers: Drafts.application.toLayer({ "drafts.read": readDraft }),
|
|
122
|
-
migrations: { loader: Migrator.fromRecord({}) },
|
|
123
123
|
name: "drafts",
|
|
124
124
|
services: Layer.empty,
|
|
125
125
|
} satisfies AppModule;
|
|
@@ -129,7 +129,7 @@ A defined module's generated handlers check each query's read policy with the mo
|
|
|
129
129
|
|
|
130
130
|
`appModules` reads a defined module's `requires` from its registration's own type, so it refuses a registration typed as `AppModule`, returned by a helper typed that way, or whose `module` is typed as `RegisteredModule`: that type has lost the services the module's handlers need. A `group` plus `handlers` registration typed as `AppModule` is refused too, because its type is the same. Declare the registration with `satisfies AppModule` instead.
|
|
131
131
|
|
|
132
|
-
`appModules` returns an Effect that rejects duplicate queue names before building any host. `DuplicateModuleQueue` from `@shivaedev/server/DuplicateModuleQueue.ts` identifies `queue`, `firstModule` and `secondModule
|
|
132
|
+
`appModules` returns an Effect that rejects duplicate queue names before building any host. `DuplicateModuleQueue` from `@shivaedev/server/DuplicateModuleQueue.ts` identifies `queue`, `firstModule` and `secondModule`, naming a defined module by its own name; repeating a name within one module also fails. It combines the native RPC groups, handler Layers, the migration loaders and schema components of the modules that declare `migrations`, skipping the rest. It includes each admin registration's group and handlers and exposes their merged registry as `modules.admin`. Migration numbers belong to one application-wide sequence. Existing hosts can continue to supply their groups, handlers, services and migrations directly.
|
|
133
133
|
|
|
134
134
|
The host builds `services` once for its lifetime and builds `requestServices` once per RPC call, including each call on a persistent WebSocket connection. Native RPC middleware supplies the request services after the contract's identity middleware resolves the caller. Declare `selfSubject` or `accountSubject` on contracts whose request services require `Subject`, `SessionUser` and `Identity`. Request services yield global dependencies from the enclosing environment; leave those global Layers out of the request Layer so they are reused. `appModules` rejects global services that require caller context or a service registered in the request slot.
|
|
135
135
|
|
|
@@ -137,6 +137,17 @@ A `defineService` declares its dependencies in `requires` and its operations yie
|
|
|
137
137
|
|
|
138
138
|
Pass `{ replacements: Layer.succeed(MyPort, implementation) }` as the second argument to `appModules`. Replacements take precedence over the combined default `ports` before module `services` acquire dependencies. Leave these ports unprovided in the module's service Layer; an adapter already captured by `Layer.provide` inside that Layer cannot be replaced from outside it. Missing ports and replacement Layer requirements remain in the host's requirement type. `workerHost` takes the same composition, provides its services to all module workers after database preparation, and scopes their lifetime to the returned Layer. Supply the shared `PgBoss` client through the service Layer in each process; the host and worker use the same module ports and replacements.
|
|
139
139
|
|
|
140
|
+
`workerHost` builds its database, services and workers inside the same redaction policy as `appHost`, and exports through the same OTLP pipeline, so do not provide `otlpTracing` around it. Once its workers are registered it logs `Worker ready to take jobs` inside that pipeline, so the application writes no readiness log of its own. Anything an application composes around the Layer that `workerHost` or `appHost` returns, such as `Layer.tap(() => Effect.logInfo(...))`, runs outside the host's redaction and exporter; put startup work in `services` or `workers` instead. Its logs, the causes its installed error reporters receive and its exported spans mask three sources: the built-in credential-shaped name rules from `@shivaedev/errors`, the names in `config.sensitiveKeys`, and the names of fields that the models of the repositories it builds mark sensitive with `sensitive: true` or a Redacted schema. A worker serves no RPC group, so no RPC schema adds names and no failure frame is masked. A job handler logs a stored row with that field as `<redacted>`, while what the job writes keeps the value. The jobs package neither logs nor reports a job's defect itself; a handler that wants one logged or reported does so in its own Effect, as `Effect.tapCause(Effect.logError)` and `Effect.withErrorReporting` do, and the worker masks both.
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
workerHost({
|
|
144
|
+
...modules,
|
|
145
|
+
postgresSettings: {},
|
|
146
|
+
config: { sensitiveKeys: ["customerReference"] },
|
|
147
|
+
migrations: { ...modules.migrations, mode: "wait" },
|
|
148
|
+
});
|
|
149
|
+
```
|
|
150
|
+
|
|
140
151
|
```ts
|
|
141
152
|
import { NodeRuntime } from "@effect/platform-node";
|
|
142
153
|
import { Layer } from "effect";
|
|
@@ -160,7 +171,7 @@ NodeRuntime.runMain(Layer.launch(Server));
|
|
|
160
171
|
|
|
161
172
|
The `sessions` Layer provides one identity `SessionPolicy` to handler middleware, sockets, change subscriptions and application routes. Construct it with `Layer.succeed(SessionPolicy, { origin, provider, roles })`; policy readers take no policy argument.
|
|
162
173
|
|
|
163
|
-
A session host also installs identity's subject resolver for contracts with `subject: selfSubject` or `subject:
|
|
174
|
+
A session host also installs identity's subject resolver for contracts with `subject: selfSubject`, `subject: accountSubject(...)` or `subject: delegatedSubject(...)`, whose rule's service the host's `services` must provide or the host fails to start. It resolves the session account or authorizes the account a call names in its `x-platform-subject` message header, falling back to that header on the transport, before the handler runs and again at each stream recheck, supplies the branded `Subject` plus the actor's `Identity` and `SessionUser` to the request, and returns the declared typed refusal when delegation is denied. Business payloads do not carry an owner id. See [declared request subjects](https://github.com/ShivaeDev/platform/tree/main/packages/identity#declared-request-subjects) for declarations and session profile requirements.
|
|
164
175
|
|
|
165
176
|
Omit `services` when the app has no service Layer of its own. The host uses `Layer.empty`; handler requirements remain explicit, and a migrated host still provides its database services to handlers. Annotated options that declare service outputs, errors or requirements must supply a `services` Layer.
|
|
166
177
|
|
|
@@ -283,7 +294,7 @@ const host = appHost({
|
|
|
283
294
|
|
|
284
295
|
Construct Better Auth inside `application`, since its constructor starts schema validation. Keep validation enabled so a current migration ledger with missing auth columns still reports drift. The starter uses this form after its pre-deploy migrations.
|
|
285
296
|
|
|
286
|
-
Railway tracing is the default error and trace destination. The starter enables tracing for both services in `.railway/railway.ts`; Railway injects the endpoint, authentication headers and service identity. `appHost`
|
|
297
|
+
Railway tracing is the default error and trace destination. The starter enables tracing for both services in `.railway/railway.ts`; Railway injects the endpoint, authentication headers and service identity. `appHost` and `workerHost` export through the redacting Effect OTLP/HTTP pipeline. Leave exporter endpoints unset on Railway so its injected configuration takes effect. Outside development mode, without an endpoint, no exporter or export loop is built, even when service metadata is set. The `http/protobuf` default follows the [OpenTelemetry recommendation](https://opentelemetry.io/docs/specs/otel/protocol/exporter/#specify-protocol); unsupported protocols, including `grpc`, fail startup with a `ConfigError` naming the value. Header and resource-attribute values are `key=value` pairs with URL-encoded values. Configuration is read through Effect Config.
|
|
287
298
|
|
|
288
299
|
The supported tracing variables and defaults are:
|
|
289
300
|
|
|
@@ -305,13 +316,12 @@ The supported tracing variables and defaults are:
|
|
|
305
316
|
|
|
306
317
|
Timeouts fail through the HTTP client's typed transport-error channel and use the same warning path as other transport failures. Effect retains its native retry policy; the request timeout applies to each attempt. The batch defaults follow Effect's `OtlpTracer.layer`. Its options cannot express a separate batch-operation deadline or a queue capacity, so `OTEL_BSP_EXPORT_TIMEOUT` controls shutdown only and `OTEL_BSP_MAX_QUEUE_SIZE` is unsupported. Other `OTEL_BSP_*` variables are unsupported.
|
|
307
318
|
|
|
308
|
-
For existing Railway services, enable manual tracing per service and environment, then redeploy. The starter does this through `tracing: { enabled: true, autoInstrumentation: false }` in its infrastructure configuration (Railway CLI 5.63.0 or newer). Railway documents that it injects the `OTEL_*` variables, including `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`, only when the app sets no endpoint of its own. The framework exports through Effect's own `effect/observability` OTLP tracer; eBPF auto-instrumentation is outside this path. For a worker, provide `otlpTracing` from `@shivaedev/server/otlpTracing.ts` to its application Layer. Railway accepts traces only: logs become `effect.log` spans with a `log` event, and Effect `ErrorReporter` reports become failed `effect.error` spans with exception events. Both use the same exporter and redaction as application spans; no OTLP logs endpoint is used. Exported diagnostic annotations mask the entire `rpc.payload`, since a request value can repeat a sensitive error field under a public payload key. The exporter batches ended Effect spans and flushes during scoped shutdown with a three-second bound by default. The first failed export logs a warning with the collector status and redacted response body, or the transport failure kind when no response arrives. Repeated failures stay quiet until a successful export. Collector connection failures and HTTP errors leave requests, jobs and shutdown successful.
|
|
319
|
+
For existing Railway services, enable manual tracing per service and environment, then redeploy. The starter does this through `tracing: { enabled: true, autoInstrumentation: false }` in its infrastructure configuration (Railway CLI 5.63.0 or newer). Railway documents that it injects the `OTEL_*` variables, including `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`, only when the app sets no endpoint of its own. The framework exports through Effect's own `effect/observability` OTLP tracer; eBPF auto-instrumentation is outside this path. `appHost` and `workerHost` export through this pipeline themselves. For a process composed without either, such as a worker built on `appDatabase` alone, provide `otlpTracing` from `@shivaedev/server/otlpTracing.ts` to its application Layer; it masks only the built-in name rules unless `RedactionPolicy` supplies a wider policy. Railway accepts traces only: logs become `effect.log` spans with a `log` event, and Effect `ErrorReporter` reports become failed `effect.error` spans with exception events. Both use the same exporter and redaction as application spans; no OTLP logs endpoint is used. Exported diagnostic annotations mask the entire `rpc.payload`, since a request value can repeat a sensitive error field under a public payload key. The exporter batches ended Effect spans and flushes during scoped shutdown with a three-second bound by default. The first failed export logs a warning with the collector status and redacted response body, or the transport failure kind when no response arrives. Repeated failures stay quiet until a successful export. Collector connection failures and HTTP errors leave requests, jobs and shutdown successful.
|
|
309
320
|
|
|
310
321
|
`appHost` mounts `POST /_platform/errors`. Mount `useBrowserErrors` from `@shivaedev/react/client/adapters/useBrowserErrors.ts` once in the root component to forward uncaught browser errors and unhandled rejections, including before sign-in. The route accepts `{ kind: "error" | "unhandledrejection", message, stack?, url }`, returns 202, and reports through the server redaction and `ErrorReporter` pipeline at Error severity. Quoted literals in browser messages and stacks are masked before reporting; diagnostic text and stack frames remain readable. It accepts at most 20 reports per minute per client IP per process, returning 429 afterwards. Railway's `x-real-ip` is used only from a configured trusted proxy; otherwise the socket peer identifies the client. Foreign origins return 403. Invalid JSON or reports over 16 KiB return 400. Limits reset with the process and are independent across replicas.
|
|
311
322
|
|
|
312
323
|
Set `browserErrors: { log: true, includeUserId: true, requireSession: true }` on `appHost` for the recommended signed-in application setting. `log` writes one Error log with the masked message and stack per accepted report, including when OTLP export is off. `includeUserId` resolves the session and adds `user.id` to the HTTP span and error report when signed in. `requireSession` rejects signed-out reports with 401; a session-provider outage returns 503. Session lookups use the host's session and origin policy. With no session policy, requiring a session rejects reports. All three options default to false, preserving reports before sign-in without session lookups or an extra log line. `browserErrorRoute(trustedProxy?, options?)` accepts the same options when composed directly.
|
|
313
324
|
|
|
314
|
-
|
|
315
325
|
With `NODE_ENV=development` and no OTLP endpoint, `appHost` and `otlpTracing` record to `node_modules/.cache/@shivaedev/server/traces.db` in the working directory using Node's SQLite support, so the store stays out of Git through the ignore entry the application already has for `node_modules`. `runDevelopment` sets this mode for its child processes. A working directory without a `node_modules` folder gets none: the store is then `traces.db` in a folder of the system's temporary directory, and a log line at startup names the file. The folder's name carries the user's id and a hash of the working directory, so it stays the same across restarts, and it is created for its owner alone. When that name is taken by a link, by another user's folder or by a folder that others can reach, the host records in a newly made private folder instead and the log line names both. Set `PLATFORM_TRACE_STORE` to choose another file and `PLATFORM_TRACE_INDEXED_ATTRIBUTES=orderId,projectId` to index application attributes. Indexed values use the same redaction as the stored spans. An explicit OTLP endpoint takes precedence; other modes without an endpoint keep export disabled.
|
|
316
326
|
|
|
317
327
|
Records flush every second on a live maintenance clock and when their scope closes. Application clock jumps do not replay flush intervals. The store retains the latest five completed recorder runs, deleting older spans, logs and attribute indexes when a recorder closes. Active recorders remain writable until their scopes close. Logs use the existing `effect.log` diagnostic spans; the `logs` view exposes their parent span ID and trace ID. Open the file with any SQLite viewer, or inspect it directly:
|
|
@@ -340,7 +350,7 @@ For a deployment behind a proxy, set `HOST=0.0.0.0` and `TRUSTED_PROXY` to a com
|
|
|
340
350
|
|
|
341
351
|
When mounting Better Auth routes yourself on Railway, use `betterAuthMount(authOptions, { clientIp: "railway" })` from `@shivaedev/identity/server/better-auth/adapters/mount.ts` with `TRUSTED_PROXY=100.64.0.0/10`. The `clientIp` preset selects `X-Real-IP` for auth and ignores spoofed `X-Forwarded-For`, overriding `AUTH_CLIENT_IP_HEADER`. Untrusted peers and requests without `X-Real-IP` use the connection address.
|
|
342
352
|
|
|
343
|
-
|
|
353
|
+
A host given an RPC group directly, rather than the `appModules` result, takes handlers for that group: build them with `Api.application.toLayer(...)` (and `Api.application.of(...)` for an Effect-built handler map), then pass the full `Api` to the host and client. `Api.application` is the native RPC group without the reserved `$changes` stream; the host supplies that handler. The explicit `Api.omit("<namespace>.$changes")` form also works.
|
|
344
354
|
|
|
345
355
|
Set `LISTEN_DATABASE_URL` to a direct or session-mode connection when `DATABASE_URL` uses a transaction pooler. `config.listenDatabaseUrl` overrides that setting; when neither is set, the listener shares the application pool. Both URLs must reach the same database. A separate listener pool reserves one connection; the application pool continues to own migrations, writes and heartbeat publication. Startup waits for the listener to receive its own heartbeat. A timeout fails the host with `PostgresListenerError` from `@shivaedev/sql/PostgresListenerError.ts`, naming the selected connection setting. Fix the URL before restarting; a startup timeout does not fall back to periodic reconnects. Established listeners retain their reconnect and Resync behavior.
|
|
346
356
|
|
|
@@ -397,7 +407,7 @@ Render inside the application's native registry provider. The query's `data` is
|
|
|
397
407
|
|
|
398
408
|
Tracing logs declared failures with `RPC failure` and their tag, and defects with `RPC defect`. Interrupt-only causes emit `RPC interrupted` at debug instead, with `rpc.method`, `requestId`, the `rpc.duration` log span and the same redacted payload. The RPC trace span carries `rpc.interrupted: true`; Effect exports interruption with an unset span status. Completed and failed RPCs receive no interruption marker. The diagnostic payload masks nested credential-shaped keys and Effect `Redacted` values. Credential-shaped strings, such as bearer tokens, URL passwords and sensitive `key=value` text, are masked too. Strings retain at most 2,048 characters before a truncation marker; collections retain at most 50 entries with a marker for the remainder, and binary values become size summaries.
|
|
399
409
|
|
|
400
|
-
`appHost` derives sensitive field names from the served RPC group's payload, success, error, defect and middleware error schemas, including nested schemas. Use `Schema.Redacted(...)`, `Schema.RedactedFromValue(...)`, or annotate a field with `sensitive: true`. The host applies each RPC's schema-derived names to that RPC's diagnostics and failures, even when a diagnostic contains an unwrapped value. Application-wide keys configured below apply to every RPC. Add other exact, case-sensitive names once in `config.sensitiveKeys`:
|
|
410
|
+
`appHost` derives sensitive field names from the served RPC group's payload, success, error, defect and middleware error schemas, including nested schemas. Use `Schema.Redacted(...)`, `Schema.RedactedFromValue(...)`, or annotate a field with `sensitive: true`. The host applies each RPC's schema-derived names to that RPC's diagnostics and failures, even when a diagnostic contains an unwrapped value. A defined module's success comes from its generated wire, which carries no annotation, so it takes no part: mark the field on the model instead. Every repository the host builds while it starts, through `makeRepository` or `makeOrderedChildren`, declares its model, and the names of the model's sensitive fields apply to every RPC and every diagnostic like `config.sensitiveKeys`, before the host serves its first request. A repository made inside a handler declares its model only when it runs, after the RPC failure masks are compiled; build repositories in Layers. Values no repository model describes, such as computed or third-party data, are covered only by the built-in name rules and `config.sensitiveKeys`. Application-wide keys configured below apply to every RPC. Add other exact, case-sensitive names once in `config.sensitiveKeys`:
|
|
401
411
|
|
|
402
412
|
```ts
|
|
403
413
|
import { Schema } from "effect";
|
|
@@ -415,7 +425,7 @@ const Server = appHost({
|
|
|
415
425
|
});
|
|
416
426
|
```
|
|
417
427
|
|
|
418
|
-
Different methods can use `state` privately and publicly in the same group. Within one method, logs and traces do not retain schema identity, so startup refuses a sensitive field name that also appears as public data in that method's payload, success, error, defect or middleware error schemas. The error names both schema paths, including nested fields and encoded names. Rename one field or give both fields the same sensitivity before starting the host. This prevents redaction of a public literal-union failure field from breaking native client decoding.
|
|
428
|
+
Different methods can use `state` privately and publicly in the same group. Within one method, logs and traces do not retain schema identity, so startup refuses a sensitive field name that also appears as public data in that method's payload, success, error, defect or middleware error schemas. The error names both schema paths, including nested fields and encoded names. Rename one field or give both fields the same sensitivity before starting the host. Model names and a module's generated success take no part in this check; a module's payload can mark a name sensitive that its generated success also names. This prevents redaction of a public literal-union failure field from breaking native client decoding.
|
|
419
429
|
|
|
420
430
|
Use `Contact` in `Api`'s RPC schemas. A `sensitive: true` annotation also applies to a checked schema, such as `Schema.String.check(Schema.isMinLength(1)).annotate({ sensitive: true })`, and to checks or groups nested inside other check groups. Values under the declared names become `<redacted>` in host log messages and annotations, failure and defect payloads sent to RPC clients, causes passed to installed error reporters, and exported trace attributes, events, links and resource attributes. Nested structured values follow the same policy before trace serialization. A field containing sensitive array items or record values is masked as a whole. `Schema.encodeKeys` and other schema encoders carry sensitivity to their declared output names, including chains of renamed fields. The host propagates encoded names and enclosing-field protection within each schema until its key set stops growing, then combines the policies for that method. Sensitivity is checked throughout each transformation's source subtree, including fields named in `config.sensitiveKeys`. Policy derivation does not execute encoder callbacks: their field provenance is unknown, so every declared output field of a sensitive source is treated as sensitive, including every union branch, otherwise public fields and error discriminators. When a sensitive source encodes to a scalar, its enclosing field is masked as a whole. Sensitive error tags are masked before tracing copies them into the `rpc.failure` log annotation. Native RPC protocol tags remain intact. An `Error` retains its message, stack and cause in redacted form. If `message` or `name` is sensitive, its stack is masked too, including stack headers encoded by `Schema.Defect({ includeStack: true })`. Successful RPC responses retain their application data. Error schemas consumed by native clients must accept the redaction marker for sensitive fields; a constrained string, numeric or collection field may otherwise fail client decoding after masking.
|
|
421
431
|
|
|
@@ -561,13 +571,15 @@ Import the module that defines the name; there is no package-root entry. Paths b
|
|
|
561
571
|
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
562
572
|
| `appHost.ts` | `appHost`: scoped HTTP and PostgreSQL composition with loopback defaults and optional proxy trust. |
|
|
563
573
|
| `appDatabase.ts` | `appDatabase`, `DatabaseConfig`: PostgreSQL composition with migrations, Reactivity and contract's `LiveServer`. |
|
|
574
|
+
| `workerHost.ts` | `workerHost`, `WorkerHostConfig`: scoped PostgreSQL, services and job workers with the host's redaction and OTLP export. |
|
|
564
575
|
| `setupDatabases.ts` | `setupDatabases()`: prepare the local development and test databases. |
|
|
565
576
|
| `development.ts` | `development({ server, worker, conditions? })`, `runDevelopment(options)`: run the server, worker and Vite in watch mode. |
|
|
566
577
|
| `rpc-server/publicConfigLayer.ts` | `publicConfigLayer(declaration, path?)`: serve a `publicConfig` declaration from native Config. |
|
|
567
578
|
| `localTracing.ts` | `localTracing(options?)`: scoped local SQLite spans and correlated logs with configurable attribute indexes and run retention. |
|
|
568
|
-
| `otlpTracing.ts` | `otlpTracing`: redacting Railway OTLP export
|
|
579
|
+
| `otlpTracing.ts` | `otlpTracing`: redacting Railway OTLP export of spans, logs and error reports for a process composed without `appHost` or `workerHost`. |
|
|
569
580
|
| `RedactionPolicy.ts` | `RedactionPolicy`: provide the app's diagnostic key predicate derived by errors. |
|
|
570
581
|
| `adapters/redactingDiagnostics.ts`, `redactingTracer.ts`, `redactingRpcSerialization.ts` | `redactingDiagnostics(sensitive)`, `redactingTracer(sensitive)`, `redactingRpcSerialization(sensitive)`: compose native diagnostic and NDJSON boundaries. `redactingRpcSerialization` reads `RpcSerialization` from the Effect environment. |
|
|
582
|
+
| `adapters/migrationsIn.ts` | `migrationsIn(directory)`: an `AppModule` `migrations` value that loads the `migrations` folder in `directory` under Node. |
|
|
571
583
|
| `adapters/makePlatformRuntime.ts` | `makePlatformRuntime(layer, { developmentCacheKey? })`. |
|
|
572
584
|
| `adapters/subscriptionSignal.ts` | `nodeSubscriptionSignal({ nodeRequest?, request?, signals? })`, returning `{ signal, dispose }`. |
|
|
573
585
|
|
package/dist/AppModule.d.ts
CHANGED
|
@@ -9,8 +9,7 @@ export type ModuleAdmin = AnyAdminRegistry & {
|
|
|
9
9
|
};
|
|
10
10
|
interface ModuleParts {
|
|
11
11
|
readonly admin?: ModuleAdmin;
|
|
12
|
-
readonly migrations
|
|
13
|
-
readonly name: string;
|
|
12
|
+
readonly migrations?: Pick<MigrationOptions<unknown, unknown>, "loader" | "components">;
|
|
14
13
|
readonly ports?: ModuleLayer;
|
|
15
14
|
readonly queues?: readonly {
|
|
16
15
|
readonly name: string;
|
|
@@ -25,10 +24,12 @@ export type AppModule = (ModuleParts & {
|
|
|
25
24
|
};
|
|
26
25
|
readonly handlers: ModuleLayer;
|
|
27
26
|
readonly module?: never;
|
|
27
|
+
readonly name: string;
|
|
28
28
|
}) | (ModuleParts & {
|
|
29
29
|
readonly group?: never;
|
|
30
30
|
readonly handlers?: never;
|
|
31
31
|
readonly module: RegisteredModule;
|
|
32
|
+
readonly name?: never;
|
|
32
33
|
});
|
|
33
34
|
export type RegisteredModule = RpcGroup.Any & Pick<AnyModule, "application" | "declaration"> & {
|
|
34
35
|
readonly "~requires": unknown;
|
package/dist/AppModule.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"AppModule.d.ts","sourceRoot":"","sources":["../src/AppModule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAAC;AAEhF,UAAU,WAAW;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC,CAAC;
|
|
1
|
+
{"version":3,"file":"AppModule.d.ts","sourceRoot":"","sources":["../src/AppModule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC;AACxD,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAAC;AAEhF,UAAU,WAAW;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC,CAAC;IACxF,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvD,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9D,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAC/B;AAID,MAAM,MAAM,SAAS,GAClB,CAAC,WAAW,GAAG;IACf,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,GAAG;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAA;KAAE,CAAC;IAChE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACrB,CAAC,GACF,CAAC,WAAW,GAAG;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAGnI,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,GAAG,GAAG,IAAI,CAAC,SAAS,EAAE,aAAa,GAAG,aAAa,CAAC,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC"}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { Effect } from "effect";
|
|
2
|
+
export declare function migrationsIn(directory: string): {
|
|
3
|
+
loader: Effect.Effect<readonly import("effect/sql/Migrator").ResolvedMigration[], import("effect/sql/Migrator").MigrationError, never>;
|
|
4
|
+
};
|
|
5
|
+
//# sourceMappingURL=migrationsIn.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"migrationsIn.d.ts","sourceRoot":"","sources":["../../src/adapters/migrationsIn.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAQ,MAAM,QAAQ,CAAC;AAItC,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM;IAE5C,MAAM;EAIP"}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import * as NodeServices from "@effect/platform-node/NodeServices";
|
|
2
|
+
import { Effect, Path } from "effect";
|
|
3
|
+
import * as MigratorFileSystem from "effect/sql/MigratorFileSystem";
|
|
4
|
+
// Node supplies the file system here, so a registration's migrations need nothing from the host that runs them.
|
|
5
|
+
export function migrationsIn(directory) {
|
|
6
|
+
return {
|
|
7
|
+
loader: Effect.flatMap(Path.Path, (path) => MigratorFileSystem.fromFileSystem(path.join(directory, "migrations"))).pipe(Effect.provide(NodeServices.layer)),
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
//# sourceMappingURL=migrationsIn.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"migrationsIn.js","sourceRoot":"","sources":["../../src/adapters/migrationsIn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,kBAAkB,MAAM,+BAA+B,CAAC;AAEpE,gHAAgH;AAChH,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC7C,OAAO;QACN,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CACtH,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,CAClC;KACD,CAAC;AACH,CAAC"}
|