@shivaedev/platform 0.16.0 → 0.17.0

package/src/server/appHost.ts

@@ -1,6 +1,8 @@
-import { Context, type Effect } from "effect";
+import { Context, type Effect, Layer } from "effect";
 import type { Rpc } from "effect/rpc";
 import type { makeLiveServer } from "@shivaedev/effect-contract/makeLiveServer.ts";
+import type { AppHostFactory } from "#server/AppHostFactory.ts";
+import type { AppHostInput, HostPreflight } from "#server/AppHostInput.ts";
 import { appHostHttp, deferredHost, migratedHost } from "#server/appHostHttp.ts";
 import { type DatabaseConfig, databaseLayer } from "#server/databaseLayer.ts";
 import type { HostOptions, HostPolicy } from "#server/hostOptions.ts";
@@ -27,11 +29,15 @@ export type AppHostOptions<
 	TServiceRequirements = never,
 	TMigrations = never,
 	TSession extends SessionShape = SessionShape,
-> = HostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements> & {
-	readonly migrations: AppDatabaseOptions<TMigrations>["migrations"];
-	readonly policy?: undefined;
-	readonly sessions: SessionPolicy<TSession>;
-};
+	TPreflight = never,
+	TPreflightError = never,
+	TPreflightRequirements = never,
+> = HostPreflight<TPreflight, TPreflightError, TPreflightRequirements> &
+	HostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements> & {
+		readonly migrations: AppDatabaseOptions<TMigrations>["migrations"];
+		readonly policy?: undefined;
+		readonly sessions: SessionPolicy<TSession>;
+	};
 
 export type AppLocalHostOptions<
 	TRpcs extends Rpc.Any,
@@ -42,11 +48,15 @@ export type AppLocalHostOptions<
 	TServiceError = never,
 	TServiceRequirements = never,
 	TMigrations = never,
-> = HostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements> & {
-	readonly migrations: AppDatabaseOptions<TMigrations>["migrations"];
-	readonly policy: "loopback";
-	readonly sessions?: never;
-};
+	TPreflight = never,
+	TPreflightError = never,
+	TPreflightRequirements = never,
+> = HostPreflight<TPreflight, TPreflightError, TPreflightRequirements> &
+	HostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements> & {
+		readonly migrations: AppDatabaseOptions<TMigrations>["migrations"];
+		readonly policy: "loopback";
+		readonly sessions?: never;
+	};
 
 export type AppHttpHostOptions<
 	TRpcs extends Rpc.Any,
@@ -57,10 +67,13 @@ export type AppHttpHostOptions<
 	TServiceError = never,
 	TServiceRequirements = never,
 	TSession extends SessionShape = SessionShape,
-> = HostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements> &
+	TPreflight = never,
+	TPreflightError = never,
+	TPreflightRequirements = never,
+> = HostPreflight<TPreflight, TPreflightError, TPreflightRequirements> &
+	HostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements> &
 	HostPolicy<TSession> & { readonly migrations?: undefined };
-
-export function appHost<
+export const appHost: AppHostFactory = <
 	TRpcs extends Rpc.Any,
 	THandlers,
 	THandlerError,
@@ -72,19 +85,11 @@ export function appHost<
 	TSession extends SessionShape = SessionShape,
 	TApplicationError = never,
 	TApplicationRequirements = never,
+	TPreflight = never,
+	TPreflightError = never,
+	TPreflightRequirements = never,
 >(
-	options:
-		| (AppDatabaseOptions<TMigrations> & {
-				readonly application: Effect.Effect<
-					AppHttpHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TSession>,
-					TApplicationError,
-					TApplicationRequirements
-				>;
-		  })
-		| AppHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TMigrations, TSession>
-		| AppLocalHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TMigrations>,
-): ReturnType<
-	typeof deferredHost<
+	options: AppHostInput<
 		TRpcs,
 		THandlers,
 		THandlerError,
@@ -95,51 +100,18 @@ export function appHost<
 		TMigrations,
 		TSession,
 		TApplicationError,
-		TApplicationRequirements
-	>
->;
-
-export function appHost<
-	TRpcs extends Rpc.Any,
-	THandlers,
-	THandlerError,
-	THandlerRequirements,
-	TServices = never,
-	TServiceError = never,
-	TServiceRequirements = never,
-	TSession extends SessionShape = SessionShape,
->(
-	options: AppHttpHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TSession>,
-): ReturnType<typeof appHostHttp<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TSession>>;
-export function appHost<
-	TRpcs extends Rpc.Any,
-	THandlers,
-	THandlerError,
-	THandlerRequirements,
-	TServices = never,
-	TServiceError = never,
-	TServiceRequirements = never,
-	TMigrations = never,
-	TSession extends SessionShape = SessionShape,
-	TApplicationError = never,
-	TApplicationRequirements = never,
->(
-	options:
-		| (AppDatabaseOptions<TMigrations> & {
-				readonly application: Effect.Effect<
-					AppHttpHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TSession>,
-					TApplicationError,
-					TApplicationRequirements
-				>;
-		  })
-		| AppHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TMigrations, TSession>
-		| AppLocalHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TMigrations>
-		| AppHttpHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TSession>,
-) {
+		TApplicationRequirements,
+		TPreflight,
+		TPreflightError,
+		TPreflightRequirements
+	>,
+) => {
 	if ("application" in options) {
-		return deferredHost(options.application, appDatabase(options));
+		return deferredHost(options.application, appDatabase(options)).pipe(Layer.provideMerge(options.preflight ?? Layer.empty));
 	}
 	return options.migrations === undefined
-		? appHostHttp(options)
-		: migratedHost({ ...options, migrations: options.migrations }, appDatabase({ ...options, migrations: options.migrations }));
-}
+		? appHostHttp(options).pipe(Layer.provideMerge(options.preflight ?? Layer.empty))
+		: migratedHost({ ...options, migrations: options.migrations }, appDatabase({ ...options, migrations: options.migrations })).pipe(
+				Layer.provideMerge(options.preflight ?? Layer.empty),
+			);
+};

package/src/server/appHostHttp.ts

@@ -4,11 +4,12 @@ import { ByteSize, Config, Effect, Layer, Option, Schema } from "effect";
 import { HttpIncomingMessage, HttpRouter, HttpServerRequest, HttpStaticServer } from "effect/http";
 import { type Rpc, RpcSerialization, RpcServer } from "effect/rpc";
 import type { Authenticated, MaybeAuthenticated, RequestTracing } from "#rpc/middleware.ts";
-import type { AppHostOptions, AppHttpHostOptions, AppLocalHostOptions } from "#server/appHost.ts";
+import type { AppHttpHostOptions } from "#server/appHost.ts";
 import { boundedRpcRequest } from "#server/boundedRpcRequest.ts";
 import type { databaseLayer } from "#server/databaseLayer.ts";
 import { healthRoute } from "#server/healthRoute.ts";
 import type { HostOptions, HostPolicy } from "#server/hostOptions.ts";
+import type { MigrationOptions } from "#server/MigrationOptions.ts";
 import { otlpTracing } from "#server/otlpTracing.ts";
 import { localRpcGuard } from "#server/rpc-server/local.ts";
 import { authenticatedLayer, maybeAuthenticatedLayer, type SessionShape } from "#server/rpc-server/session.ts";
@@ -96,9 +97,8 @@ export function migratedHost<
 	TMigrations,
 	TSession extends SessionShape,
 >(
-	options:
-		| AppHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TMigrations, TSession>
-		| AppLocalHostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements, TMigrations>,
+	options: HostOptions<TRpcs, THandlers, THandlerError, THandlerRequirements, TServices, TServiceError, TServiceRequirements> &
+		HostPolicy<TSession> & { readonly migrations: MigrationOptions<TMigrations> },
 	database: ReturnType<typeof databaseLayer<TMigrations>>,
 ) {
 	const services = Layer.mergeAll(options.services ?? Layer.empty);

package/src/server/rpc-server/adapters/betterAuthSessions.ts

@@ -1,4 +1,4 @@
-import { Effect, Option } from "effect";
+import { Effect, Option, Predicate } from "effect";
 import type { Headers } from "effect/http";
 import { AuthUnavailable } from "#errors/taxonomy.ts";
 import type { ProviderAccountValue } from "#rpc/identity.ts";
@@ -28,10 +28,18 @@ export function betterAuthSessions<TSession extends SessionShape>(getSession: Ge
 			if (resolved === null || getProviderAccounts === undefined) {
 				return resolved;
 			}
-			const accounts = await getProviderAccounts(transport);
+			const accounts = await getProviderAccounts(transport).catch((cause: unknown) => {
+				if (Predicate.hasProperty(cause, "statusCode") && cause.statusCode === 401) {
+					return null;
+				}
+				throw cause;
+			});
+			if (accounts === null) {
+				return null;
+			}
 			return {
 				...resolved,
-				user: { ...resolved.user, providerAccounts: accounts.map(({ accountId, providerId }) => ({ accountId, providerId })) },
+				user: { ...resolved.user, providerAccounts: accounts },
 			};
 		}).pipe(Effect.catch((error) => unavailable(error.cause)));
 		return Option.fromNullishOr(session);

package/docs/north-star.md

@@ -1,36 +0,0 @@
-# North star
-
-## The problem
-
-A service can express its work clearly in Effect and still lose that clarity at its boundary. An HTTP request arrives with cookies and headers; native RPC supplies middleware arguments; an authentication provider returns a Promise; a database transaction replaces a service for one invocation; and a test must reach all of them together. Rebuilding that glue in each application gives the same concepts different names and leaves room for differences that matter: credentials taken from an RPC message, a shared Layer holding one user's identity, an outage mistaken for a missing session, or a Promise call escaping the test's transaction.
-
-Callers also need a common language for expected failures. A field rejection should arrive with its field and message, while a defect should remain a defect and diagnostics should not expose its credentials. Neither concern belongs in each feature's business logic.
-
-## The ideal
-
-An application declares errors and native RPC middleware in modules its browser can import. The server supplies a session provider and an explicit Origin policy, and a handler reads a small request-local identity service. It then makes its own resource-authorization decision. The same request id identifies the invocation in its handler, logs and span.
-
-A Promise boundary uses the application's runtime and its invocation's services. A long-lived Node response has one cancellation signal and an explicit cleanup function. An application using Better Auth with Effect Prisma can store its auth rows through that runtime. An application using Prisma and tRPC can set up its test composition once and write feature tests against the caller and database in one rollback transaction.
-
-These are separate entry modules. The core request/error/runtime work should require Effect alone. Optional storage and test composition should load their own peers only when selected.
-
-## Which trade-offs win
-
-1. **Native Effect semantics.** Typed failures, invocation-local services, interruption and transaction scope matter more than a short integration example. A convenience must not hide a boundary that its caller needs to reason about.
-2. **An explicit source of trust.** HTTP authentication and Origin decisions use transport headers, not values an RPC message can override. The request id is correlation data a caller may choose; it must not become an authorization credential. A provider outage must remain distinct from an anonymous caller.
-3. **One owner for each job.** Platform supplies shared request services and the glue across boundaries. Native repositories belong to effect-sql, declarations to effect-contract, services to effect-service and generic test execution to effect-test. The optional adapters compose effect-prisma and effect-trpc rather than implementing them again.
-4. **Useful evidence and diagnostics.** Describe the composition a test actually runs. A bounded redactor can reduce common credential leaks; it cannot decide every application's sensitive fields or justify putting secrets in messages. Keep application-specific data policy explicit.
-5. **Small conveniences.** A provider function, a Layer and a defining-module import are preferable to a second configuration language or application container. Add a helper when it removes repeated work while leaving the native pieces visible.
-
-## What the package deliberately leaves out
-
-- Authentication-provider selection, OAuth configuration, cookies, session lifetimes and client refresh policy.
-- Resource ownership and role checks. An authenticated user id is input to authorization, not permission to access every resource.
-- Application transports, CORS configuration, subscription limits, event buses and deployment policy.
-- A native SQL auth storage choice. Session resolution can use a provider without making its storage part of the application's repository model.
-- A second service container, RPC framework, persistence model or generic test runner.
-- Guarantees about SSR isolation, mobile cookie persistence or a particular Node/Bun host inferred from local fixtures.
-
-## Where planning belongs
-
-[The package roadmap](roadmap.md) owns changes to these modules, their evidence and the maintainer's scope decisions. [The framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md) owns composed fixtures, application adoption and deployment validation across packages.

package/docs/roadmap.md

@@ -1,31 +0,0 @@
-# Roadmap
-
-This file owns Platform's module implementation, package tests and scope questions. The [framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md) owns cross-package fixtures, application adoption and browser, mobile and deployment validation.
-
-## Built
-
-- [x] `localRpcGuard` rejects unknown or non-loopback transport addresses before calling the handler and accepts known IPv4, IPv6 and mapped loopback addresses. [Injected-request evidence](https://github.com/ShivaeDev/platform/blob/main/packages/platform/src/server/rpc-server/local.test.ts); this is separate from deployed host or proxy validation.
-- [x] `rpcBoundary` passes declared errors and successes through, normalizes unexpected failures and defects to a declared rejection with a redacted public message, retains the original cause off the wire, and preserves interruption, including mixed failure/cancellation causes. [Boundary evidence](https://github.com/ShivaeDev/platform/blob/main/packages/platform/src/server/rpc-server/boundary.test.ts).
-- [x] Shared Schema tagged errors and field-rejection extraction, with native RPC JSON and tRPC rejection tests.
-- [x] Browser-safe native RPC middleware declarations and request-id, identity and optional-identity services, with compile-time checks on guarded handlers.
-- [x] Request-local session middleware, a Better Auth session-provider boundary and an explicit Origin policy. Tests cover concurrent identities, anonymous callers, provider failures and rejection before provider lookup.
-- [x] HTTP transport-header authentication, direct tests of the RPC-header fallback and HTTP-header precedence, and a WebSocket protocol fixture that uses upgrade-request headers instead of RPC message credentials. [Header selection evidence](https://github.com/ShivaeDev/platform/blob/main/packages/platform/src/server/rpc-server/transportHeaders.test.ts).
-- [x] Request-id log/span annotations and redaction of failure payloads, defects, reported causes and credential-shaped strings, with bounded collection and string output. [Tracing tests](https://github.com/ShivaeDev/platform/blob/main/packages/platform/src/server/rpc-server/tracing.test.ts) cover successful requests and interruption without failure logs.
-- [x] An application runtime that acquires its Layer once, releases it exactly once, shares an explicit development cache key and recreates disposed cache entries, bypasses caching in production, and carries service overrides across Promise calls. [Runtime tests](https://github.com/ShivaeDev/platform/blob/main/packages/platform/src/server/runtime/makePlatform.test.ts) cover typed Layer build failures, Promise rejection, signal interruption with finalization, and nested override replacement and restoration.
-- [x] Node subscription cancellation from Web/procedure signals and simulated request/socket close events, with listener cleanup.
-- [x] A Better Auth Effect Prisma database adapter and Prisma/tRPC rollback harness. Real PostgreSQL tests cover shared transactions, failed transaction rollback, selected row operations and harness types; they require `PLATFORM_EFFECT_PRISMA_TEST_DATABASE_URL`.
-- [x] Better Auth adapter filters preserve PostgreSQL null, membership, comparison and literal-pattern semantics, including nonunique updates, OR-filter updates and deletes, and rejection of nonstring patterns. Configured model names map by default. Reads retain their filters through selection, ascending/descending ordering and limit/offset pagination; experimental native joins are rejected for both single and collection reads. [Adapter boundary tests](../src/server/better-auth/filterBoundaries.spec.ts) assert these paths against PostgreSQL.
-- [x] Packed-consumer checks for defining-module imports, types and core entries installed without optional peers.
-- [x] A local app host Layer and reusable database Layer, extracted from the PostgreSQL composition: migrations before services, guarded NDJSON RPC, session policy, static assets, scoped shutdown and commit-bound live delivery. The composed fixture covers two HTTP server processes and a worker. Fleet’s daemon adopts `appHost` and `appDatabase` with a custom RPC route, session-free loopback policy and its existing migration ledger. Platform’s real HTTP option tests cover hosting without a database, while Fleet’s PostgreSQL daemon tests cover pool limits, migration upgrades and existing clients.
-
-## Next
-
-- [ ] Add focused adapter tests for the remaining public options, `debugLogs` and `usePlural`.
-
-## Open questions
-
-- What comprehensive application redaction policy should cover span names, free text and custom attributes, and how should request/action correlation work across boundaries?
-
-- Should the package keep the optional Better Auth storage adapter and Prisma/tRPC harness beside its native request-context modules, or should those compositions live with the integration packages? Both serve real boundary work, but they give this package a wider surface than its request-identity job alone.
-- If an application needs Better Auth storage on native Effect SQL, should Platform own that adapter or should the provider retain separate storage? The request middleware needs a session provider, not a particular database.
-- The exports make Better Auth translation helpers importable beside the adapter. Are these helpers intended as supported consumer APIs, or should a future public API change narrow the surface to the adapter?