@satorio/machinery 0.2.1

package/dist/graphql/builder.js

@@ -0,0 +1,35 @@
+import SchemaBuilder from '@pothos/core';
+import '@pothos/plugin-directives';
+import '@pothos/plugin-sub-graph';
+import DirectivesPlugin from '@pothos/plugin-directives';
+import FederationPlugin, { hasResolvableKey } from '@pothos/plugin-federation';
+import SubGraphPlugin from '@pothos/plugin-sub-graph';
+/**
+ * The two variations of one schema: `Public` (external) and `Internal`
+ * (admin and service operations). Federation (`@key` + `resolveReference`)
+ * turns each variation into a subgraph for the gateway.
+ *
+ * @internal
+ */
+export const SUB_GRAPH_NAMES = ['Public', 'Internal'];
+/**
+ * The federation and subgraph settings every schema in this package
+ * shares, fixed here so two services cannot drift apart.
+ *
+ * @internal
+ */
+export const subGraphOptions = {
+    defaultForTypes: [...SUB_GRAPH_NAMES],
+    fieldsInheritFromTypes: true,
+    explicitlyIncludeType: (type) => hasResolvableKey(type),
+};
+/**
+ * Returns a builder factory carrying the resolver context type. The context
+ * itself belongs to your service, so this returns a factory, not a ready
+ * instance. Every service shares the same plugins and subgraph settings,
+ * fixed here.
+ */
+export const makeSubGraphSchemaBuilder = () => new SchemaBuilder({
+    plugins: [DirectivesPlugin, FederationPlugin, SubGraphPlugin],
+    subGraphs: subGraphOptions,
+});

package/dist/graphql/context.d.ts

@@ -0,0 +1,36 @@
+import { type Effect, Exit, ParseResult } from 'effect';
+import { GraphQLError } from 'graphql';
+import type { OperationFailure } from './failures.js';
+/**
+ * Maps a GraphQL failure to a `GraphQLError`: the same three-class operation
+ * failure channel, plus input decoder failures — no second catalog. Names
+ * and details come from the domain failure and land in `extensions.code`.
+ */
+export declare const asGraphQLError: (failure: OperationFailure | ParseResult.ParseError) => GraphQLError;
+/**
+ * Runs the use case's Effect program and returns its result: a success
+ * value, a `GraphQLError` for a typed failure, or `INTERNAL` for a defect.
+ */
+/**
+ * @internal
+ */
+export type RunOperations<R> = <A>(program: Effect.Effect<A, OperationFailure | ParseResult.ParseError, R>) => Promise<A>;
+/**
+ * The minimal capability a resolver borrows from the runtime: run a program
+ * that needs `R` and return its `Exit`. Both `Runtime.runPromiseExit` and
+ * `ManagedRuntime.runPromiseExit` fit this shape, so production and tests
+ * share one code path.
+ */
+export type RunOperationsExit<R> = <A, E>(program: Effect.Effect<A, E, R>) => Promise<Exit.Exit<A, E>>;
+/**
+ * What a resolver reads from its context: one call that runs a use
+ * case's program and answers with its value or a `GraphQLError`.
+ */
+export interface GraphQLContext<R> {
+    readonly runOperations: RunOperations<R>;
+}
+/**
+ * Builds that context around the runtime's own `runPromiseExit`, so a
+ * resolver never touches the runtime directly.
+ */
+export declare const graphqlContextFrom: <R>(runExit: RunOperationsExit<R>) => GraphQLContext<R>;

package/dist/graphql/context.js

@@ -0,0 +1,69 @@
+import { Cause, Exit, Option, ParseResult } from 'effect';
+import { GraphQLError } from 'graphql';
+/**
+ * Maps a GraphQL failure to a `GraphQLError`: the same three-class operation
+ * failure channel, plus input decoder failures — no second catalog. Names
+ * and details come from the domain failure and land in `extensions.code`.
+ */
+export const asGraphQLError = (failure) => {
+    switch (failure._tag) {
+        case 'SubjectNotFoundError':
+            return new GraphQLError(`${failure.subject} ${failure.id} not found`, {
+                extensions: {
+                    code: 'NOT_FOUND',
+                    reason: 'subject-not-found',
+                    subject: failure.subject,
+                    id: failure.id,
+                },
+            });
+        case 'OperationRejectedError':
+            return new GraphQLError(`${failure.reason}: ${failure.detail}`, {
+                extensions: {
+                    code: 'REJECTED',
+                    reason: failure.reason,
+                    detail: failure.detail,
+                },
+            });
+        case 'OperationsUnavailableError':
+            return new GraphQLError(`Service unavailable: ${failure.operation}`, {
+                extensions: {
+                    code: 'UNAVAILABLE',
+                    reason: 'service-unavailable',
+                    operation: failure.operation,
+                },
+            });
+        case 'ParseError': {
+            const detail = ParseResult.TreeFormatter.formatErrorSync(failure);
+            return new GraphQLError(`Invalid input: ${detail.split('\n')[0]}`, {
+                extensions: {
+                    code: 'BAD_USER_INPUT',
+                    reason: 'invalid-input',
+                    detail,
+                },
+            });
+        }
+        default:
+            return new GraphQLError('Unknown failure', {
+                extensions: { code: 'INTERNAL', reason: 'internal-error' },
+            });
+    }
+};
+/**
+ * Builds that context around the runtime's own `runPromiseExit`, so a
+ * resolver never touches the runtime directly.
+ */
+export const graphqlContextFrom = (runExit) => ({
+    runOperations: async (program) => {
+        const exit = await runExit(program);
+        if (Exit.isSuccess(exit)) {
+            return exit.value;
+        }
+        const failure = Cause.failureOption(exit.cause);
+        if (Option.isSome(failure)) {
+            throw asGraphQLError(failure.value);
+        }
+        throw new GraphQLError('Internal service error', {
+            extensions: { code: 'INTERNAL', detail: Cause.pretty(exit.cause) },
+        });
+    },
+});

package/dist/graphql/failure-classification.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The proof that every failure a service can raise is mapped at this
+ * boundary. Give it the union of your own failures and the union of the
+ * tags your resolver classifies, then assign `true` to it once, beside
+ * the lists. A failure nobody classified turns the type into that
+ * failure's own tag, so the compiler stops and names it rather than
+ * letting it reach a caller as `INTERNAL`.
+ */
+export type EveryFailureIsClassified<Failures extends {
+    readonly _tag: string;
+}, Classified extends string> = [Exclude<Failures['_tag'], Classified>] extends [never] ? true : Exclude<Failures['_tag'], Classified>;

package/dist/graphql/failure-classification.js

@@ -0,0 +1 @@
+export {};

package/dist/graphql/failures.d.ts

@@ -0,0 +1,62 @@
+import type { Refusal } from '@satorio/machinery/core';
+declare const SubjectNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SubjectNotFoundError";
+} & Readonly<A>;
+/**
+ * One of exactly three operation failure classes below — the closed set a
+ * resolver maps to. An untagged failure is a defect, not a domain error.
+ */
+export declare class SubjectNotFoundError extends SubjectNotFoundError_base<{
+    readonly subject: string;
+    readonly id: string;
+}> {
+}
+declare const OperationRejectedError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "OperationRejectedError";
+} & Readonly<A>;
+/**
+ * A resolver's rule rejected the operation, and `reason` names the cause it
+ * recognized.
+ *
+ * `reason` is the named cause from the service's shared failure taxonomy when
+ * a domain failure is recognized; otherwise it is the tag of the rule that
+ * rejected the operation.
+ */
+export declare class OperationRejectedError extends OperationRejectedError_base<{
+    readonly rule: string;
+    readonly reason: string;
+    readonly detail: string;
+}> {
+}
+declare const OperationsUnavailableError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "OperationsUnavailableError";
+} & Readonly<A>;
+/**
+ * A resolver's own dependency did not answer; `cause` carries the port's own
+ * failure.
+ */
+export declare class OperationsUnavailableError extends OperationsUnavailableError_base<{
+    readonly operation: string;
+    readonly cause: unknown;
+}> {
+}
+/**
+ * Everything a resolver may fail with, as one closed set: not found, rejected,
+ * or unavailable.
+ */
+export type OperationFailure = SubjectNotFoundError | OperationRejectedError | OperationsUnavailableError;
+declare const ServerCannotListenError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ServerCannotListenError";
+} & Readonly<A>;
+/**
+ * The socket never opened. `port` is the port the server asked for, and
+ * `refusal` says in three parts which variable decides that port and how
+ * to hand it another one.
+ */
+export declare class ServerCannotListenError extends ServerCannotListenError_base<{
+    readonly port: number;
+    readonly refusal: Refusal;
+    readonly cause: unknown;
+}> {
+}
+export {};

package/dist/graphql/failures.js

@@ -0,0 +1,30 @@
+import { Data } from 'effect';
+/**
+ * One of exactly three operation failure classes below — the closed set a
+ * resolver maps to. An untagged failure is a defect, not a domain error.
+ */
+export class SubjectNotFoundError extends Data.TaggedError('SubjectNotFoundError') {
+}
+/**
+ * A resolver's rule rejected the operation, and `reason` names the cause it
+ * recognized.
+ *
+ * `reason` is the named cause from the service's shared failure taxonomy when
+ * a domain failure is recognized; otherwise it is the tag of the rule that
+ * rejected the operation.
+ */
+export class OperationRejectedError extends Data.TaggedError('OperationRejectedError') {
+}
+/**
+ * A resolver's own dependency did not answer; `cause` carries the port's own
+ * failure.
+ */
+export class OperationsUnavailableError extends Data.TaggedError('OperationsUnavailableError') {
+}
+/**
+ * The socket never opened. `port` is the port the server asked for, and
+ * `refusal` says in three parts which variable decides that port and how
+ * to hand it another one.
+ */
+export class ServerCannotListenError extends Data.TaggedError('ServerCannotListenError') {
+}

package/dist/graphql/graphiql.d.ts

@@ -0,0 +1,45 @@
+import { type GraphQLSchema } from 'graphql';
+/**
+ * A GraphiQL page: a title and a pre-filled document. Your service writes
+ * the examples, since only it knows its schema's operations; the machinery
+ * supplies the form, a neutral default, and a check the example still fits.
+ */
+export interface GraphiqlPage {
+    readonly title: string;
+    readonly defaultQuery: string;
+}
+/**
+ * The page a service gets before it writes examples of its own: one
+ * introspection query and a note saying where to write more.
+ *
+ * @internal
+ */
+export declare const DEFAULT_GRAPHIQL_PAGE: GraphiqlPage;
+/**
+ * @internal
+ */
+export interface GraphiqlExampleProblem {
+    readonly message: string;
+}
+/**
+ * Checks a GraphiQL page's default query against a schema. An example that
+ * no longer matches the schema is worse than none — it teaches the wrong
+ * thing. A service's test runs its page through this check on every change.
+ */
+export declare const graphiqlExampleProblems: (schema: GraphQLSchema, page: GraphiqlPage) => readonly GraphiqlExampleProblem[];
+/**
+ * A minimal schema the default page must stay valid against: it asks only
+ * for introspection, nothing more, so it fits any real schema too.
+ *
+ * @internal
+ */
+export declare const MINIMAL_SCHEMA_FOR_DEFAULT_PAGE: GraphQLSchema;
+/**
+ * The shape Yoga takes for its editor page.
+ *
+ * @internal
+ */
+export declare const graphiqlOptionsFor: (page: GraphiqlPage) => {
+    readonly title: string;
+    readonly defaultQuery: string;
+};

package/dist/graphql/graphiql.js

@@ -0,0 +1,56 @@
+import { buildSchema, parse, validate } from 'graphql';
+/**
+ * The page a service gets before it writes examples of its own: one
+ * introspection query and a note saying where to write more.
+ *
+ * @internal
+ */
+export const DEFAULT_GRAPHIQL_PAGE = {
+    title: 'Machinery — Internal GraphQL',
+    defaultQuery: `# Place your cursor inside an operation and press ▶ to run it.
+# Each field and argument description lives in the schema — see the Docs
+# tab on the right.
+#
+# Your service supplies example operations here. Until it does,
+# introspection shows the schema.
+
+query Introspection {
+  __schema {
+    queryType {
+      name
+    }
+  }
+}
+`,
+};
+/**
+ * Checks a GraphiQL page's default query against a schema. An example that
+ * no longer matches the schema is worse than none — it teaches the wrong
+ * thing. A service's test runs its page through this check on every change.
+ */
+export const graphiqlExampleProblems = (schema, page) => {
+    try {
+        return validate(schema, parse(page.defaultQuery)).map((error) => ({
+            message: error.message,
+        }));
+    }
+    catch (cause) {
+        return [{ message: cause instanceof Error ? cause.message : String(cause) }];
+    }
+};
+/**
+ * A minimal schema the default page must stay valid against: it asks only
+ * for introspection, nothing more, so it fits any real schema too.
+ *
+ * @internal
+ */
+export const MINIMAL_SCHEMA_FOR_DEFAULT_PAGE = buildSchema('type Query { ping: String }');
+/**
+ * The shape Yoga takes for its editor page.
+ *
+ * @internal
+ */
+export const graphiqlOptionsFor = (page) => ({
+    title: page.title,
+    defaultQuery: page.defaultQuery,
+});

package/dist/graphql/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public entry to the graphql mechanism: one server that answers your
+ * operations and the readiness probes beside them. It gives you one Yoga
+ * server on Bun that serves a federated Pothos schema and the readiness probes
+ * on the same port, with a resolver context that runs your use cases and turns
+ * their typed failures into one closed set of `GraphQLError` codes.
+ */
+export { makeSubGraphSchemaBuilder } from './builder.js';
+export { asGraphQLError, type GraphQLContext, graphqlContextFrom, type RunOperationsExit, } from './context.js';
+export type { EveryFailureIsClassified } from './failure-classification.js';
+export { type OperationFailure, OperationRejectedError, OperationsUnavailableError, ServerCannotListenError, SubjectNotFoundError, } from './failures.js';
+export { type GraphiqlPage, graphiqlExampleProblems, } from './graphiql.js';
+export { graphqlServerLive } from './layer.js';
+export { makeYogaServer } from './server.js';
+export { ENVIRONMENT, GRAPHQL_ENDPOINT, graphiqlEnabledFromEnvironment, graphqlPortFromEnvironment, serverCannotListen, } from './settings.js';

package/dist/graphql/index.js

@@ -0,0 +1,14 @@
+/**
+ * Public entry to the graphql mechanism: one server that answers your
+ * operations and the readiness probes beside them. It gives you one Yoga
+ * server on Bun that serves a federated Pothos schema and the readiness probes
+ * on the same port, with a resolver context that runs your use cases and turns
+ * their typed failures into one closed set of `GraphQLError` codes.
+ */
+export { makeSubGraphSchemaBuilder } from './builder.js';
+export { asGraphQLError, graphqlContextFrom, } from './context.js';
+export { OperationRejectedError, OperationsUnavailableError, ServerCannotListenError, SubjectNotFoundError, } from './failures.js';
+export { graphiqlExampleProblems, } from './graphiql.js';
+export { graphqlServerLive } from './layer.js';
+export { makeYogaServer } from './server.js';
+export { ENVIRONMENT, GRAPHQL_ENDPOINT, graphiqlEnabledFromEnvironment, graphqlPortFromEnvironment, serverCannotListen, } from './settings.js';

package/dist/graphql/layer.d.ts

@@ -0,0 +1,15 @@
+import { type ConfigError, Layer } from 'effect';
+import type { ServerCannotListenError } from './failures.js';
+import { type GraphQLRequestHandlerOptions } from './request-handler.js';
+/**
+ * The one layer this mechanism mounts: the server that answers your
+ * operations.
+ *
+ * The one layer this mechanism mounts: it opens the port, keeps `Bun.serve`
+ * alive for the life of the scope, and serves both GraphQL and the readiness
+ * probes (`/livez`, `/readyz`, `/healthz`) from one handler, so the probes
+ * answer on the SAME port as the schema. A port the runtime cannot open comes
+ * back as `ServerCannotListenError`, whose refusal names the variable that
+ * decides it.
+ */
+export declare const graphqlServerLive: <R>(options: GraphQLRequestHandlerOptions<R>) => Layer.Layer<never, ConfigError.ConfigError | ServerCannotListenError, R>;

package/dist/graphql/layer.js

@@ -0,0 +1,23 @@
+import { Effect, Layer } from 'effect';
+import { graphqlRequestHandler, } from './request-handler.js';
+import { graphqlPortFromEnvironment, serverCannotListen } from './settings.js';
+/**
+ * The one layer this mechanism mounts: the server that answers your
+ * operations.
+ *
+ * The one layer this mechanism mounts: it opens the port, keeps `Bun.serve`
+ * alive for the life of the scope, and serves both GraphQL and the readiness
+ * probes (`/livez`, `/readyz`, `/healthz`) from one handler, so the probes
+ * answer on the SAME port as the schema. A port the runtime cannot open comes
+ * back as `ServerCannotListenError`, whose refusal names the variable that
+ * decides it.
+ */
+export const graphqlServerLive = (options) => Layer.scopedDiscard(Effect.gen(function* () {
+    const port = yield* graphqlPortFromEnvironment;
+    const fetchHandler = yield* graphqlRequestHandler(options);
+    yield* Effect.acquireRelease(Effect.try({
+        try: () => Bun.serve({ port, fetch: fetchHandler }),
+        catch: (cause) => serverCannotListen(port, cause),
+    }), (server) => Effect.promise(() => server.stop(true)));
+    yield* Effect.logInfo(`GraphQL (Yoga) and readiness probes are listening on port ${port}`);
+}));

package/dist/graphql/request-handler.d.ts

@@ -0,0 +1,26 @@
+import { type NamedHealthCheck } from '@satorio/machinery/http';
+import { type ConfigError, Effect } from 'effect';
+import type { GraphQLSchema } from 'graphql';
+import type { GraphiqlPage } from './graphiql.js';
+/**
+ * What a service hands this mechanism to be served: its schema, the
+ * readiness checks that answer beside it, and the editor page it wants a
+ * reader to open on.
+ *
+ * @internal
+ */
+export interface GraphQLRequestHandlerOptions<R> {
+    readonly schema: GraphQLSchema;
+    readonly graphiqlPage?: GraphiqlPage;
+    readonly healthChecks: Effect.Effect<readonly NamedHealthCheck<R>[], ConfigError.ConfigError, R>;
+}
+/**
+ * One handler for one port: the readiness routes answer first, and
+ * everything they do not claim goes to GraphQL. It captures the Effect
+ * runtime carrying the service's ports, so a resolver runs a use case
+ * from it. Whatever opens the socket — `Bun.serve` in production, a
+ * plain server in a test — serves this one function.
+ *
+ * @internal
+ */
+export declare const graphqlRequestHandler: <R>(options: GraphQLRequestHandlerOptions<R>) => Effect.Effect<(request: Request) => Promise<Response>, ConfigError.ConfigError, R>;

package/dist/graphql/request-handler.js

@@ -0,0 +1,33 @@
+import { healthRoutesFetch, } from '@satorio/machinery/http';
+import { Effect, Runtime } from 'effect';
+import { graphqlContextFrom } from './context.js';
+import { makeYogaServer } from './server.js';
+import { graphiqlEnabledFromEnvironment } from './settings.js';
+/**
+ * One handler for one port: the readiness routes answer first, and
+ * everything they do not claim goes to GraphQL. It captures the Effect
+ * runtime carrying the service's ports, so a resolver runs a use case
+ * from it. Whatever opens the socket — `Bun.serve` in production, a
+ * plain server in a test — serves this one function.
+ *
+ * @internal
+ */
+export const graphqlRequestHandler = (options) => Effect.gen(function* () {
+    const graphiqlEnabled = yield* graphiqlEnabledFromEnvironment;
+    const healthChecks = yield* options.healthChecks;
+    const runtime = yield* Effect.runtime();
+    const runCheck = Runtime.runPromiseExit(runtime);
+    const yoga = makeYogaServer({
+        schema: options.schema,
+        ...(options.graphiqlPage === undefined
+            ? {}
+            : { graphiqlPage: options.graphiqlPage }),
+        context: graphqlContextFrom(runCheck),
+        graphiqlEnabled,
+    });
+    const health = healthRoutesFetch({ runCheck, checks: healthChecks });
+    return async (request) => {
+        const healthResponse = await health(request);
+        return healthResponse ?? (await yoga.fetch(request));
+    };
+});

package/dist/graphql/server.d.ts

@@ -0,0 +1,19 @@
+import type { GraphQLSchema } from 'graphql';
+import { type YogaServerInstance } from 'graphql-yoga';
+import type { GraphQLContext } from './context.js';
+import { type GraphiqlPage } from './graphiql.js';
+/**
+ * @internal
+ */
+export interface GraphQLServerOptions<R> {
+    readonly schema: GraphQLSchema;
+    readonly graphiqlPage?: GraphiqlPage;
+    readonly context: GraphQLContext<R>;
+    readonly graphiqlEnabled?: boolean;
+}
+/**
+ * Builds a Yoga GraphQL server for Bun. The `graphiqlEnabled` flag only
+ * turns off the editor page; the endpoint itself keeps answering either
+ * way.
+ */
+export declare const makeYogaServer: <R>(options: GraphQLServerOptions<R>) => YogaServerInstance<Record<string, never>, GraphQLContext<R>>;

package/dist/graphql/server.js

@@ -0,0 +1,16 @@
+import { createYoga } from 'graphql-yoga';
+import { DEFAULT_GRAPHIQL_PAGE, graphiqlOptionsFor, } from './graphiql.js';
+import { GRAPHIQL_ENABLED_BY_DEFAULT, GRAPHQL_ENDPOINT } from './settings.js';
+/**
+ * Builds a Yoga GraphQL server for Bun. The `graphiqlEnabled` flag only
+ * turns off the editor page; the endpoint itself keeps answering either
+ * way.
+ */
+export const makeYogaServer = (options) => createYoga({
+    schema: options.schema,
+    context: () => options.context,
+    graphqlEndpoint: GRAPHQL_ENDPOINT,
+    graphiql: (options.graphiqlEnabled ?? GRAPHIQL_ENABLED_BY_DEFAULT)
+        ? graphiqlOptionsFor(options.graphiqlPage ?? DEFAULT_GRAPHIQL_PAGE)
+        : false,
+});

package/dist/graphql/settings.d.ts

@@ -0,0 +1,55 @@
+import { type EnvironmentEntry, type Refusal } from '@satorio/machinery/core';
+import { Config } from 'effect';
+import { ServerCannotListenError } from './failures.js';
+/**
+ * The port the server listens on when nobody names one.
+ *
+ * @internal
+ */
+export declare const DEFAULT_GRAPHQL_PORT = 4000;
+/**
+ * GraphiQL is the editor served on the same endpoint: opening `/graphql`
+ * in a browser loads the schema docs and examples. It defaults to on
+ * because the endpoint is internal; production turns it off with
+ * `GRAPHIQL_ENABLED=false`.
+ *
+ * @internal
+ */
+export declare const GRAPHIQL_ENABLED_BY_DEFAULT = true;
+/**
+ * The one path the GraphQL endpoint answers on. Readiness probes mount
+ * beside it, on the same port.
+ */
+export declare const GRAPHQL_ENDPOINT = "/graphql";
+/**
+ * The three parts a reader meets when the port is set to something the
+ * server cannot listen on. A port left unset takes the default and
+ * refuses nothing.
+ *
+ * @internal
+ */
+export declare const portRefusal: Refusal;
+/**
+ * Every variable this adapter reads, and the one state each of them
+ * stands in. Neither is prefixed: one process serves one schema, so
+ * these two names are whole.
+ */
+export declare const ENVIRONMENT: readonly EnvironmentEntry[];
+/**
+ * The port to listen on. Unset, it falls back to the default; set to
+ * anything outside the range a TCP port can take, it refuses in three
+ * parts.
+ */
+export declare const graphqlPortFromEnvironment: Config.Config<number>;
+/**
+ * Whether to serve the editor page. The endpoint itself answers either
+ * way; only the page in a browser goes away.
+ */
+export declare const graphiqlEnabledFromEnvironment: Config.Config<boolean>;
+/**
+ * Turns whatever the runtime threw while opening the socket into the
+ * named failure a caller reads. The text names the variable that decides
+ * the port and the port it asked for, because the runtime's own message
+ * names neither.
+ */
+export declare const serverCannotListen: (port: number, cause: unknown) => ServerCannotListenError;

package/dist/graphql/settings.js

@@ -0,0 +1,82 @@
+import { fallsBackTo, wholeNumberFallingBackTo, } from '@satorio/machinery/core';
+import { Config } from 'effect';
+import { ServerCannotListenError } from './failures.js';
+const PORT = 'GRAPHQL_PORT';
+const GRAPHIQL_ENABLED = 'GRAPHIQL_ENABLED';
+const LOWEST_PORT = 1;
+const HIGHEST_PORT = 65_535;
+/**
+ * The port the server listens on when nobody names one.
+ *
+ * @internal
+ */
+export const DEFAULT_GRAPHQL_PORT = 4000;
+/**
+ * GraphiQL is the editor served on the same endpoint: opening `/graphql`
+ * in a browser loads the schema docs and examples. It defaults to on
+ * because the endpoint is internal; production turns it off with
+ * `GRAPHIQL_ENABLED=false`.
+ *
+ * @internal
+ */
+export const GRAPHIQL_ENABLED_BY_DEFAULT = true;
+/**
+ * The one path the GraphQL endpoint answers on. Readiness probes mount
+ * beside it, on the same port.
+ */
+export const GRAPHQL_ENDPOINT = '/graphql';
+/**
+ * The three parts a reader meets when the port is set to something the
+ * server cannot listen on. A port left unset takes the default and
+ * refuses nothing.
+ *
+ * @internal
+ */
+export const portRefusal = {
+    what: `${PORT} is set to something this server cannot listen on.`,
+    why: `A TCP port is a whole number from ${LOWEST_PORT} to ${HIGHEST_PORT}, and nothing else can be opened.`,
+    whatToDo: `Set ${PORT} to a whole number in that range, or leave it unset and take the ${DEFAULT_GRAPHQL_PORT} default.`,
+};
+/**
+ * Every variable this adapter reads, and the one state each of them
+ * stands in. Neither is prefixed: one process serves one schema, so
+ * these two names are whole.
+ */
+export const ENVIRONMENT = [
+    {
+        name: PORT,
+        what: 'The port the GraphQL endpoint and the readiness probes listen on.',
+        state: fallsBackTo(String(DEFAULT_GRAPHQL_PORT)),
+    },
+    {
+        name: GRAPHIQL_ENABLED,
+        what: 'Whether the GraphiQL editor page is served on the same endpoint.',
+        state: fallsBackTo(String(GRAPHIQL_ENABLED_BY_DEFAULT)),
+    },
+];
+/**
+ * The port to listen on. Unset, it falls back to the default; set to
+ * anything outside the range a TCP port can take, it refuses in three
+ * parts.
+ */
+export const graphqlPortFromEnvironment = wholeNumberFallingBackTo(PORT, LOWEST_PORT, HIGHEST_PORT, DEFAULT_GRAPHQL_PORT, portRefusal);
+/**
+ * Whether to serve the editor page. The endpoint itself answers either
+ * way; only the page in a browser goes away.
+ */
+export const graphiqlEnabledFromEnvironment = Config.boolean(GRAPHIQL_ENABLED).pipe(Config.withDefault(GRAPHIQL_ENABLED_BY_DEFAULT));
+/**
+ * Turns whatever the runtime threw while opening the socket into the
+ * named failure a caller reads. The text names the variable that decides
+ * the port and the port it asked for, because the runtime's own message
+ * names neither.
+ */
+export const serverCannotListen = (port, cause) => new ServerCannotListenError({
+    port,
+    cause,
+    refusal: {
+        what: `This service could not open port ${port}.`,
+        why: `${PORT} decides which port the GraphQL endpoint and the readiness probes listen on, and it takes ${DEFAULT_GRAPHQL_PORT} when nobody names one. A port another process already holds refuses the socket.`,
+        whatToDo: `Free port ${port}, or set ${PORT} to a port nothing else holds, then start the service again.`,
+    },
+});