@shivaedev/server 0.39.0 → 0.41.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 CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.41.0 - 2026-11-21
4
+
5
+ ### Added
6
+
7
+ - when the host closes an RPC socket because a message exceeds `maxBodySize` or `MAX_BODY_SIZE`, it logs one warning with the limit, the message size and the RPC path, annotated as `rpc.maxBodySize`, `rpc.messageSize` and `url.path`, and none of the message's content. The size is `unknown` when the Node listener's WebSocket server refuses the message before the host reads it.
8
+
9
+ ## 0.40.0 - 2026-11-21
10
+
11
+ ### Added
12
+
13
+ - `servedGroup(group, websocket)` from `@shivaedev/server/servedGroup.ts` and `servedHandlers(group, handlers, buildVersion?)` from `@shivaedev/server/servedHandlers.ts` are the composition `appHost` serves its RPC group with: the read policy guard, which refuses `$changes` over HTTP, the command guard, the change stream, the host version and live sync. A native RPC host uses them to serve as `appHost` does.
14
+
3
15
  ## 0.39.0 - 2026-11-21
4
16
 
5
17
  ### Added
package/README.md CHANGED
@@ -102,6 +102,8 @@ const hosts = Effect.gen(function* () {
102
102
  });
103
103
  ```
104
104
 
105
+ An application built with [`@shivaedev/build`](https://github.com/ShivaeDev/platform/tree/main/packages/build#the-servers-module-list) writes no such list: its generator finds every exported registration written `satisfies AppModule` and writes them to `src/generated/server/modules.ts` in the order of their files' paths, and the application passes that list to `appModules` beside the registrations that are not module folders, such as its foundation, so a module is registered by creating its folder. Admin navigation and the order in which `appModules` composes Layers follow the list. What the merged Layers provide and the migrations do not depend on it, because migrations run by their number. An application that needs another order renames a module's folder, or composes that registration beside its foundation where the generator does not find it, such as a function that returns it.
106
+
105
107
  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 handlers need the services its operations' `run` and read policies yield, less what its middleware and subject provide per call; the registration's `services` and `ports` provide them, 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
108
 
107
109
  ```ts
@@ -248,13 +250,13 @@ Set `config.socketPath` to serve the application over a Unix socket instead of t
248
250
 
249
251
  Unix clients can call HTTP RPC and subscribe through WebSocket RPC over the same socket path. Unix requests use filesystem access for transport admission; session middleware and query read policies still apply. TCP keeps its loopback, origin and proxy checks.
250
252
 
251
- RPC request bodies are limited to 1 MiB by default. Set `MAX_BODY_SIZE` to a byte count or override it with `config.maxBodySize`, a nonnegative safe integer. An oversized NDJSON body, fixed-length or chunked, returns a 4xx before any RPC handler runs. The same byte limit applies to each WebSocket RPC message, including binary messages and the combined payload of continuation frames. An oversized message closes the connection with code 1009 before any RPC in that message runs; native Effect socket clients receive a typed `SocketError` with a `SocketCloseError` reason. The limit includes bearer authentication frames, and zero refuses every nonempty message. This limit applies to the host's RPC route.
253
+ RPC request bodies are limited to 1 MiB by default. Set `MAX_BODY_SIZE` to a byte count or override it with `config.maxBodySize`, a nonnegative safe integer. An oversized NDJSON body, fixed-length or chunked, returns a 4xx before any RPC handler runs. The same byte limit applies to each WebSocket RPC message, including binary messages and the combined payload of continuation frames. The limit is per message and the same for every RPC on the socket; no operation has a limit of its own. An oversized message closes the whole connection with code 1009 before any RPC in that message runs, so every call in flight on it fails; native Effect socket clients receive a typed `SocketError` with a `SocketCloseError` reason. The host logs one warning for each refusal with the limit, the message size and the RPC path, annotated as `rpc.maxBodySize`, `rpc.messageSize` and `url.path`, and never any of the message's content. The size is `unknown` when the Node listener's WebSocket server refuses the message as it arrives, before the host reads it. The limit includes bearer authentication frames, and zero refuses every nonempty message. This limit applies to the host's RPC route.
252
254
 
253
255
  For a native Node HTTP route outside RPC, read the request body with `readBoundedBody` from [`@shivaedev/http`](https://github.com/ShivaeDev/platform/tree/main/packages/http#readme), which rejects oversized bodies with a typed 413 failure.
254
256
 
255
257
  On TCP, ordinary POST RPC uses `localRpcGuard` from `@shivaedev/identity/server/adapters/local.ts`: it requires a loopback peer and Host, same-origin or absent Origin, and the NDJSON content type. The WebSocket upgrade uses the same loopback, origin and trusted-proxy checks without an HTTP body content type. Session lookup uses the upgrade's transport headers; RPC message headers cannot replace its cookie or Origin. Session middleware revalidates authenticated streams at `streamRevalidationInterval` and ends revoked subscriptions with typed `Unauthorized`. Cookie-authenticated sockets remain open; later protected calls use the same session checks. Automatic live subscriptions reload the session before each hint and use its current roles and grants for the query policy and any pushed query result. A policy denial keeps an established subscription open; delivery resumes on the next authorized hint. POST RPC refuses `$changes` subscriptions with the contract’s typed `WebSocketRequired` error and a message saying they need the WebSocket protocol. The host applies `RequestTracing` last to every served RPC, including loopback RPC, so it wraps authentication and handlers without a per-contract tracing declaration. Existing tracing declarations run once at that outermost boundary. With a session policy, contracts declare `Authenticated` and `MaybeAuthenticated` as needed; the host supplies their implementations. For `AuthenticatedUser`, merge `authenticatedUserLayer()` from `@shivaedev/identity/server/session.ts` beside the handlers. Declared errors retain their Schema types. Applications still own resource authorization and use `rpcBoundary` when they need to map unexpected failures.
256
258
 
257
- Native clients that cannot set upgrade headers use `makeClient`'s `bearerToken` option from `@shivaedev/contract/bind.ts`. On session hosts, `GET /rpc?auth=frame` requires a first text frame shaped as `{"_tag":"Authenticate","token":"<credential>"}` within five seconds, with at most 8192 characters. The host consumes that frame before starting native RPC and supplies its bearer as the socket's transport Authorization header. The existing session provider, identity middleware, Origin policy and query read policies apply to every call and live read. RPC message headers cannot replace the authenticated credential. Configure bearer admission on the session provider and the WebView Origin through `nativeOrigins`. A long-lived bearer is never placed in a URL.
259
+ Native clients that cannot set upgrade headers use `makeClient`'s `bearerToken` option from `@shivaedev/contract/makeClient.ts`. On session hosts, `GET /rpc?auth=frame` requires a first text frame shaped as `{"_tag":"Authenticate","token":"<credential>"}` within five seconds, with at most 8192 characters. The host consumes that frame before starting native RPC and supplies its bearer as the socket's transport Authorization header. The existing session provider, identity middleware, Origin policy and query read policies apply to every call and live read. RPC message headers cannot replace the authenticated credential. Configure bearer admission on the session provider and the WebView Origin through `nativeOrigins`. A long-lived bearer is never placed in a URL.
258
260
 
259
261
  Invalid, expired, malformed, oversized or missing first-frame credentials close the socket with code 1008 and reason `Authentication required`; session-provider failures close it with code 1011 and reason `Authentication unavailable`. The host checks the bearer socket's session at `streamRevalidationInterval`, including when no subscription is active, and closes it with code 1008 when the session is revoked, expires or changes identity. The session remains subject to the same per-call and per-hint checks as cookie sessions.
260
262
 
@@ -355,7 +357,7 @@ To pass worker-release time in a story, build `hostTime()` from `@shivaedev/test
355
357
 
356
358
  For a deployment behind a proxy, set `HOST=0.0.0.0` and `TRUSTED_PROXY` to a comma-separated list of proxy peer IPs or CIDR ranges (IPv4 or IPv6), or use `config.host` and `config.trustedProxy`. Only matching peers may supply `X-Forwarded-Host` and `X-Forwarded-Proto` (`http` or `https`) for the guard's same-origin check; the proxy must overwrite both headers and preserve Origin. A single authority is required, and comma-separated forwarding chains are refused. IPv4-mapped IPv6 peers match their IPv4 address. A session host bound to a non-loopback address refuses to boot without `TRUSTED_PROXY` or `config.trustedProxy`, with a typed `TrustedProxyRequired` error from `@shivaedev/server/TrustedProxyRequired.ts` naming both settings and how to supply proxy peer addresses or CIDR ranges. Local loopback hosts keep working without proxy trust; `policy: "loopback"` does not use proxy trust. Malformed addresses or ranges fail `appHost` startup with a typed `ConfigError`. The starter's Railway deployment works out of the box: its web configuration supplies `TRUSTED_PROXY=100.64.0.0/10` and `AUTH_CLIENT_IP_HEADER=x-real-ip`, so matching peers supply forwarded client IPs for auth and the HTTPS authority for RPC origin checks. Set `PUBLIC_URL` to the app's HTTPS URL for secure session cookies. NDJSON and the application's session Origin policy still apply. See the [deployment quickstart](https://github.com/ShivaeDev/platform/blob/main/docs/framework/quickstart.md#deploy).
357
359
 
358
- When mounting Better Auth routes yourself on Railway, use `betterAuthMount(authOptions, { clientIp: "railway" })` from `@shivaedev/identity/server/better-auth/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.
360
+ When mounting Better Auth routes yourself on Railway, use `betterAuthMount(AppAuth, { clientIp: "railway" })` from `@shivaedev/identity/server/better-auth/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.
359
361
 
360
362
  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.
361
363
 
@@ -392,16 +394,14 @@ export const Server = appHost({
392
394
 
393
395
  `publicConfigLayer` reads `Config.schema` from the host's native ConfigProvider when the handler Layer builds. Missing or invalid required fields fail startup with a typed `ConfigError`. An optional second argument supplies a native Config path: `publicConfigLayer(PublicConfig, "PUBLIC")` reads `PUBLIC_INSTALL_URL` with the default environment provider. Only schema-declared fields are loaded and serialized; other server values never enter this response. The generated query has no session middleware, so it can supply public configuration before sign-in. Merge it alongside authenticated contracts rather than applying authentication to the merged group.
394
396
 
395
- On the client, use the same contract `makeClient` and shared WebSocket as other queries:
397
+ On the client, put the contract in the record of the same `makeClient` as the other contracts, on the shared WebSocket:
396
398
 
397
399
  ```ts
398
- import { makeClient } from "@shivaedev/contract/bind.ts";
400
+ import { makeClient } from "@shivaedev/contract/makeClient.ts";
399
401
  import { useQuery } from "@shivaedev/react/client/resultState.ts";
400
402
  import { PublicConfig } from "./public-config.ts";
401
403
 
402
- const { api: config } = makeClient(PublicConfig, {
403
- url: new URL("/rpc", window.location.href).href,
404
- });
404
+ const { config } = makeClient({ config: PublicConfig }).api;
405
405
 
406
406
  export function usePublicConfig() {
407
407
  return useQuery(config.get.query());
@@ -477,7 +477,7 @@ A nested `runWithServices` call replaces the outer invocation's overrides for it
477
477
 
478
478
  ### Node subscriptions: combine cancellation and clean up
479
479
 
480
- A native host that builds `hostChanges(group)` supplies its ordinary RPC handlers with `hostChanges(group).pipe(Layer.provideMerge(handlers))`. These are Layer dependencies because the subscription executes the authorized query handlers to produce its first result. `appHost` supplies them automatically.
480
+ A native RPC host serves what `appHost` serves through two pieces. `yield* servedGroup(group, websocket)` from `@shivaedev/server/servedGroup.ts` returns the `group` to serve, with the read policy guard and the command guard in place, and the `guards` Layer to provide: a host with `websocket: false` refuses `$changes` calls with `WebSocketRequired`, as `appHost`'s HTTP route does. `servedHandlers(group, handlers, buildVersion?)` from `@shivaedev/server/servedHandlers.ts` adds the group's change stream, the host version and live sync to the application's handlers; the change stream depends on the ordinary handlers because a subscription runs the authorized query to produce its first result. `appHost` composes both itself.
481
481
 
482
482
  A long-lived response can receive cancellation from a Web request, a procedure and its underlying Node connection:
483
483
 
@@ -589,6 +589,7 @@ Import the module that defines the name; there is no package-root entry. Paths b
589
589
  | `migrationsIn.ts` | `migrationsIn(directory)`: an `AppModule` `migrations` value that loads the `migrations` folder in `directory` under Node. |
590
590
  | `adapters/makePlatformRuntime.ts` | `makePlatformRuntime(layer, { developmentCacheKey? })`. |
591
591
  | `subscriptionSignal.ts` | `nodeSubscriptionSignal({ nodeRequest?, request?, signals? })`, returning `{ signal, dispose }`. |
592
+ | `servedGroup.ts`, `servedHandlers.ts` | `servedGroup(group, websocket)`, `servedHandlers(group, handlers, buildVersion?)`: the served group, guards and handlers `appHost` composes, for a native RPC host. |
592
593
 
593
594
  ### Install, setup and limits
594
595