@thomasfosterau/effect-sparql-node 0.0.0 → 0.1.0

package/src/SparqlApi.ts

@@ -0,0 +1,506 @@
+/**
+ * The SPARQL 1.1 Protocol and Graph Store HTTP Protocol as an Effect
+ * `HttpApi` definition: the endpoints, their parameters, request media types,
+ * response media types and error statuses, shared by the server
+ * (`SparqlApiBuilder`), the derived client
+ * (`SparqlApiClient`) and the OpenAPI document
+ * (`openApi`).
+ *
+ * The API has two groups:
+ *
+ * - `sparql`: `query` (`GET` with `?query=`, or without it for the service
+ *   description) and `post` (`POST` with an
+ *   `application/x-www-form-urlencoded`, `application/sparql-query` or
+ *   `application/sparql-update` body);
+ * - `graphStore`: `get`, `head`, `put`, `post` and `delete` on the graph store
+ *   with `?graph=<iri>` or `?default`, with RDF bodies under every media type
+ *   of the default `Formats`.
+ *
+ * Content negotiation (`Accept`) and `405 Method Not Allowed` are not part of
+ * the definition: the server's handlers negotiate with the same code as
+ * `SparqlServer`, and `SparqlApiBuilder` answers the methods the API does not
+ * declare. A request whose parameters the API's schemas reject (a repeated
+ * `query` or `graph`, say) is handed to the protocol handler too, by the
+ * `SchemaFallback` middleware, so it gets the protocol's own `400` and
+ * message. Error bodies are `text/plain` messages decoded into
+ * `ProtocolErrors.ProtocolError`.
+ *
+ * This module only describes the API, so a client can import it without the
+ * server. `effect/http-api` is `@stability unstable` in Effect 4, and this
+ * definition follows it.
+ *
+ * @since 0.1.0
+ */
+import * as Arr from 'effect/Array';
+import * as Schema from 'effect/Schema';
+import * as SchemaTransformation from 'effect/SchemaTransformation';
+import * as HttpApi from 'effect/http-api/HttpApi';
+import * as HttpApiEndpoint from 'effect/http-api/HttpApiEndpoint';
+import * as HttpApiGroup from 'effect/http-api/HttpApiGroup';
+import * as HttpApiMiddleware from 'effect/http-api/HttpApiMiddleware';
+import * as HttpApiSchema from 'effect/http-api/HttpApiSchema';
+import * as OpenApi from 'effect/http-api/OpenApi';
+import type * as Serialization from '@thomasfosterau/effect-rdf/Serialization';
+import type * as Engine from '@thomasfosterau/effect-rdf/sparql/Engine';
+import * as Results from '@thomasfosterau/effect-rdf/sparql/Results';
+import type * as Store from '@thomasfosterau/effect-rdf/sparql/Store';
+import * as ProtocolErrors from '@thomasfosterau/effect-rdf/sparql/ProtocolErrors';
+import * as ServerFormats from '@thomasfosterau/effect-rdf/sparql/ServerFormats';
+import * as Protocol from '@thomasfosterau/effect-rdf/sparql/Protocol';
+
+// -----------------------------------------------------------------------------
+// Media types
+// -----------------------------------------------------------------------------
+
+/**
+ * The media types of the default RDF formats (`ServerFormats.codecs`), in order of
+ * preference: Graph Store bodies and `CONSTRUCT` / `DESCRIBE` / service
+ * description responses.
+ *
+ * @since 0.1.0
+ * @category media types
+ */
+export const rdfMediaTypes: ReadonlyArray<string> = Arr.dedupe(
+  Arr.flatMap(ServerFormats.codecs, (codec) => codec.format.mediaTypes),
+);
+
+/**
+ * The media types of SPARQL results (`Results.codecs`): JSON, XML, CSV and
+ * TSV, in order of preference.
+ *
+ * @since 0.1.0
+ * @category media types
+ */
+export const resultsMediaTypes: ReadonlyArray<string> = Arr.dedupe(
+  Arr.flatMap(Results.codecs, (codec) => codec.format.mediaTypes),
+);
+
+/**
+ * Every media type a query response can have: the results formats for
+ * `SELECT` / `ASK`, then the RDF formats for `CONSTRUCT` / `DESCRIBE` and the
+ * service description.
+ *
+ * @since 0.1.0
+ * @category media types
+ */
+export const queryMediaTypes: ReadonlyArray<string> = Arr.dedupe(
+  Arr.appendAll(resultsMediaTypes, rdfMediaTypes),
+);
+
+// -----------------------------------------------------------------------------
+// Schemas
+// -----------------------------------------------------------------------------
+
+/**
+ * A query response body: a byte stream under any of `queryMediaTypes`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const QueryResponse: HttpApiSchema.StreamUint8Array = HttpApiSchema.StreamUint8Array({
+  contentType: queryMediaTypes,
+});
+
+/**
+ * An RDF document response body: a byte stream under any of `rdfMediaTypes`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const RdfResponse: HttpApiSchema.StreamUint8Array = HttpApiSchema.StreamUint8Array({
+  contentType: rdfMediaTypes,
+});
+
+const iris = Schema.optionalKey(Schema.Array(Schema.String));
+
+/**
+ * The `Accept` request header, which selects the response format.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const AcceptHeader = Schema.Struct({ accept: Schema.optionalKey(Schema.String) });
+
+/**
+ * The decoded type of `AcceptHeader`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type AcceptHeader = typeof AcceptHeader.Type;
+
+/**
+ * The query string of a query: the query and its protocol dataset.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const QueryParams = Schema.Struct({
+  query: Schema.optionalKey(Schema.String),
+  'default-graph-uri': iris,
+  'named-graph-uri': iris,
+});
+
+/**
+ * The decoded type of `QueryParams`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type QueryParams = typeof QueryParams.Type;
+
+/**
+ * The query string of a `POST`: the protocol dataset of a query
+ * (`default-graph-uri` / `named-graph-uri`) or of an update
+ * (`using-graph-uri` / `using-named-graph-uri`).
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const DatasetParams = Schema.Struct({
+  'default-graph-uri': iris,
+  'named-graph-uri': iris,
+  'using-graph-uri': iris,
+  'using-named-graph-uri': iris,
+});
+
+/**
+ * The decoded type of `DatasetParams`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type DatasetParams = typeof DatasetParams.Type;
+
+/**
+ * An `application/x-www-form-urlencoded` `POST` body holding a `query` or an
+ * `update` and its protocol dataset.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const FormBody = Schema.Struct({
+  query: Schema.optionalKey(Schema.String),
+  update: Schema.optionalKey(Schema.String),
+  'default-graph-uri': iris,
+  'named-graph-uri': iris,
+  'using-graph-uri': iris,
+  'using-named-graph-uri': iris,
+}).pipe(HttpApiSchema.asFormUrlEncoded());
+
+/**
+ * The decoded type of `FormBody`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type FormBody = typeof FormBody.Type;
+
+/**
+ * An `application/sparql-query` `POST` body, decoded as
+ * `{ _tag: 'DirectQuery', query }`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const DirectQueryBody = Schema.String.pipe(
+  Schema.decodeTo(
+    Schema.TaggedStruct('DirectQuery', { query: Schema.String }),
+    SchemaTransformation.transform({
+      decode: (query) => ({ _tag: 'DirectQuery' as const, query }),
+      encode: (body) => body.query,
+    }),
+  ),
+  HttpApiSchema.asText({ contentType: Protocol.SPARQL_QUERY }),
+);
+
+/**
+ * The decoded type of `DirectQueryBody`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type DirectQueryBody = typeof DirectQueryBody.Type;
+
+/**
+ * An `application/sparql-update` `POST` body, decoded as
+ * `{ _tag: 'DirectUpdate', update }`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const DirectUpdateBody = Schema.String.pipe(
+  Schema.decodeTo(
+    Schema.TaggedStruct('DirectUpdate', { update: Schema.String }),
+    SchemaTransformation.transform({
+      decode: (update) => ({ _tag: 'DirectUpdate' as const, update }),
+      encode: (body) => body.update,
+    }),
+  ),
+  HttpApiSchema.asText({ contentType: Protocol.SPARQL_UPDATE }),
+);
+
+/**
+ * The decoded type of `DirectUpdateBody`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type DirectUpdateBody = typeof DirectUpdateBody.Type;
+
+const rdfDocument = (mediaType: string) =>
+  Schema.String.pipe(
+    Schema.decodeTo(
+      Schema.Struct({ mediaType: Schema.Literal(mediaType), document: Schema.String }),
+      SchemaTransformation.transform({
+        decode: (document) => ({ mediaType, document }),
+        encode: (body) => body.document,
+      }),
+    ),
+    HttpApiSchema.asText({ contentType: mediaType }),
+  );
+
+/**
+ * Graph Store request bodies: an RDF document under one of `rdfMediaTypes`,
+ * decoded as `{ mediaType, document }` (the media type selects the request's
+ * `Content-Type`).
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const RdfDocumentBody = Arr.map(rdfMediaTypes, rdfDocument);
+
+/**
+ * The query string of a Graph Store request: `graph=<iri>` (indirect
+ * identification) or `default` (the default graph).
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const GraphParams = Schema.Struct({
+  graph: Schema.optionalKey(Schema.String),
+  default: Schema.optionalKey(Schema.String),
+});
+
+/**
+ * The decoded type of `GraphParams`.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export type GraphParams = typeof GraphParams.Type;
+
+/**
+ * The error response of a status: a `text/plain` message, decoded as an
+ * `ProtocolErrors.ProtocolError` with that status.
+ *
+ * @since 0.1.0
+ * @category schemas
+ */
+export const ProtocolErrorResponse = (status: number) =>
+  Schema.String.pipe(
+    Schema.decodeTo(
+      ProtocolErrors.ProtocolError.pipe(
+        Schema.check(
+          Schema.makeFilter((error: ProtocolErrors.ProtocolError) => error.status === status, {
+            identifier: `ProtocolError${status}`,
+            title: `ProtocolError (${status})`,
+            description: `A protocol error with status ${status}`,
+          }),
+        ),
+      ),
+      SchemaTransformation.transform({
+        decode: (message) => ({
+          _tag: 'ProtocolError' as const,
+          status,
+          message: message.trimEnd(),
+        }),
+        encode: (error) => `${error.message}\n`,
+      }),
+    ),
+    HttpApiSchema.asText({ contentType: 'text/plain' }),
+    HttpApiSchema.status(status),
+  );
+
+const BadRequest = ProtocolErrorResponse(400);
+const Forbidden = ProtocolErrorResponse(403);
+const NotFound = ProtocolErrorResponse(404);
+const MethodNotAllowed = ProtocolErrorResponse(405);
+const NotAcceptable = ProtocolErrorResponse(406);
+const UnsupportedMediaType = ProtocolErrorResponse(415);
+const InternalServerError = ProtocolErrorResponse(500);
+const ServiceUnavailable = ProtocolErrorResponse(503);
+
+// -----------------------------------------------------------------------------
+// The API
+// -----------------------------------------------------------------------------
+
+/**
+ * Middleware on every endpoint that answers a request whose parameters or
+ * headers fail the API's schemas with the protocol handler instead of an
+ * empty `400` (see `SparqlApiBuilder.layerSchemaFallback`). It needs the
+ * server's services and nothing on the client side.
+ *
+ * @since 0.1.0
+ * @category middleware
+ */
+export class SchemaFallback extends HttpApiMiddleware.Service<
+  SchemaFallback,
+  { requires: Engine.SparqlEngine | Store.QuadStore | Serialization.Formats }
+>()('@thomasfosterau/effect-sparql-node/SparqlApi/SchemaFallback') {}
+
+/**
+ * The paths an API is served at.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Paths {
+  /** The SPARQL endpoint, for queries and updates (default `/sparql`). */
+  readonly path?: `/${string}` | undefined;
+  /** The Graph Store endpoint (default `/rdf-graph-store`). */
+  readonly graphStorePath?: `/${string}` | undefined;
+}
+
+const sparqlGroup = (path: `/${string}`) =>
+  HttpApiGroup.make('sparql')
+    .add(
+      HttpApiEndpoint.get('query', path, {
+        query: QueryParams,
+        headers: AcceptHeader,
+        success: QueryResponse,
+        error: [BadRequest, NotAcceptable, InternalServerError, ServiceUnavailable],
+      }).annotateMerge(
+        OpenApi.annotations({
+          summary: 'Query, or read the service description',
+          description:
+            'A SPARQL query in `query`, with its dataset in `default-graph-uri` / `named-graph-uri`. Without `query`, answers the service description. The response format is negotiated from `Accept`.',
+        }),
+      ),
+      HttpApiEndpoint.post('post', path, {
+        query: DatasetParams,
+        headers: AcceptHeader,
+        payload: [DirectQueryBody, DirectUpdateBody, FormBody],
+        success: [QueryResponse, HttpApiSchema.NoContent],
+        error: [
+          BadRequest,
+          Forbidden,
+          NotAcceptable,
+          UnsupportedMediaType,
+          InternalServerError,
+          ServiceUnavailable,
+        ],
+      }).annotateMerge(
+        OpenApi.annotations({
+          summary: 'Query or update',
+          description:
+            'A query (`200` with the results) or an update (`204`), as a form or as an `application/sparql-query` / `application/sparql-update` body. A read-only endpoint answers updates with `403`.',
+        }),
+      ),
+    )
+    .annotateMerge(
+      OpenApi.annotations({ title: 'SPARQL', description: 'The SPARQL 1.1 Protocol' }),
+    );
+
+const writeErrors = [
+  BadRequest,
+  NotFound,
+  MethodNotAllowed,
+  UnsupportedMediaType,
+  InternalServerError,
+] as const;
+
+const graphStoreGroup = (path: `/${string}`) =>
+  HttpApiGroup.make('graphStore')
+    .add(
+      HttpApiEndpoint.get('get', path, {
+        query: GraphParams,
+        headers: AcceptHeader,
+        success: RdfResponse,
+        error: [BadRequest, NotFound, NotAcceptable, InternalServerError],
+      }).annotateMerge(OpenApi.annotations({ summary: 'Read a graph' })),
+      HttpApiEndpoint.head('head', path, {
+        query: GraphParams,
+        headers: AcceptHeader,
+        success: HttpApiSchema.Empty(200),
+        error: [BadRequest, NotFound, NotAcceptable, InternalServerError],
+      }).annotateMerge(OpenApi.annotations({ summary: 'Check that a graph exists' })),
+      HttpApiEndpoint.put('put', path, {
+        query: GraphParams,
+        payload: RdfDocumentBody,
+        success: [HttpApiSchema.NoContent, HttpApiSchema.Created],
+        error: writeErrors,
+      }).annotateMerge(
+        OpenApi.annotations({
+          summary: 'Replace a graph',
+          description: '`201` when the graph is new, `204` when it existed.',
+        }),
+      ),
+      HttpApiEndpoint.post('post', path, {
+        query: GraphParams,
+        payload: RdfDocumentBody,
+        success: [HttpApiSchema.NoContent, HttpApiSchema.Created],
+        error: writeErrors,
+      }).annotateMerge(
+        OpenApi.annotations({
+          summary: 'Add to a graph, or create one',
+          description:
+            'Merges the document into the graph (`201` when it is new). Without `graph` or `default`, creates a new graph and answers `201` with its IRI in `Location`.',
+        }),
+      ),
+      HttpApiEndpoint.delete('delete', path, {
+        query: GraphParams,
+        success: HttpApiSchema.NoContent,
+        error: [BadRequest, NotFound, MethodNotAllowed, InternalServerError],
+      }).annotateMerge(OpenApi.annotations({ summary: 'Delete a graph' })),
+    )
+    .annotateMerge(
+      OpenApi.annotations({
+        title: 'Graph Store',
+        description:
+          'The SPARQL 1.1 Graph Store HTTP Protocol (indirect identification; URLs below the graph store identify graphs directly)',
+      }),
+    );
+
+/**
+ * Builds the API at the given paths.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = (paths?: Paths) =>
+  HttpApi.make('effect-sparql-node')
+    .add(sparqlGroup(paths?.path ?? '/sparql'))
+    .add(graphStoreGroup(paths?.graphStorePath ?? '/rdf-graph-store'))
+    .middleware(SchemaFallback)
+    .annotateMerge(
+      OpenApi.annotations({
+        title: 'SPARQL 1.1 Protocol and Graph Store HTTP Protocol',
+        description:
+          'Every response format is negotiated from `Accept`; methods an endpoint does not support are answered with `405` and `Allow`.',
+      }),
+    );
+
+/**
+ * The type of an API built by `make`.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type Api = ReturnType<typeof make>;
+
+/**
+ * The API at the default paths, `/sparql` and `/rdf-graph-store`.
+ *
+ * @since 0.1.0
+ * @category api
+ */
+export const SparqlApi: Api = make();
+
+/**
+ * The OpenAPI document of an API (the default one when omitted).
+ *
+ * @since 0.1.0
+ * @category openapi
+ */
+export const openApi = (api: Api = SparqlApi): OpenApi.OpenAPISpec => OpenApi.fromApi(api);

package/src/SparqlApiBuilder.ts

@@ -0,0 +1,196 @@
+/**
+ * Serves the `SparqlApi` definition with `HttpApiBuilder`.
+ *
+ * Every endpoint is implemented with a raw handler (`handleRaw`) that runs
+ * the same code as `SparqlServer`: the request body, `Accept` and
+ * `Content-Type` are read by the protocol internals, so responses, statuses
+ * and error messages are those of `SparqlServer.handler`. Routes the API does
+ * not declare (other methods on the endpoints, which get `405` with
+ * `Allow`; `OPTIONS` preflights when CORS is on; graphs identified directly
+ * by a URL below the graph store) are registered as plain `HttpRouter`
+ * fallback routes to `SparqlServer.handler`.
+ *
+ * `effect/http-api` is `@stability unstable` in Effect 4.
+ *
+ * @since 0.1.0
+ */
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Scope from 'effect/Scope';
+import type * as HttpClient from 'effect/http/HttpClient';
+import * as HttpRouter from 'effect/http/HttpRouter';
+import * as HttpServer from 'effect/http/HttpServer';
+import * as HttpServerError from 'effect/http/HttpServerError';
+import * as HttpApiBuilder from 'effect/http-api/HttpApiBuilder';
+import * as HttpApiMiddleware from 'effect/http-api/HttpApiMiddleware';
+import type * as Options from '@thomasfosterau/effect-rdf/sparql/Options';
+import * as SparqlApi from './SparqlApi.ts';
+import * as SparqlServer from '@thomasfosterau/effect-rdf/sparql/SparqlServer';
+import * as Testing from '@thomasfosterau/effect-rdf/sparql/Testing';
+
+/**
+ * Options of the API server: the server options, with the endpoint paths of
+ * the API (the update endpoint is the query endpoint) and where to serve the
+ * OpenAPI document.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface ApiOptions
+  extends Omit<Options.Options, 'path' | 'updatePath' | 'graphStorePath'>, SparqlApi.Paths {
+  /** Serves the OpenAPI document (`SparqlApi.openApi`) as JSON at this path. */
+  readonly openapiPath?: `/${string}` | undefined;
+}
+
+interface ServerPaths {
+  readonly path: `/${string}`;
+  readonly graphStorePath: `/${string}`;
+}
+
+const serverOptions = (options?: ApiOptions): Options.Options & ServerPaths => {
+  const path = options?.path ?? '/sparql';
+  return {
+    ...options,
+    path,
+    updatePath: path,
+    graphStorePath: options?.graphStorePath ?? '/rdf-graph-store',
+  };
+};
+
+const handlersFor = (api: SparqlApi.Api, options: Options.Options) => {
+  const sparql = SparqlServer.sparqlHandler(options);
+  const graphStore = SparqlServer.graphStoreHandler(options);
+  return Layer.mergeAll(
+    HttpApiBuilder.group(api, 'sparql', (handlers) =>
+      handlers.handleRaw('query', () => sparql).handleRaw('post', () => sparql),
+    ),
+    HttpApiBuilder.group(api, 'graphStore', (handlers) =>
+      handlers
+        .handleRaw('get', () => graphStore)
+        .handleRaw('head', () => graphStore)
+        .handleRaw('put', () => graphStore)
+        .handleRaw('post', () => graphStore)
+        .handleRaw('delete', () => graphStore),
+    ),
+  );
+};
+
+/**
+ * The handlers of both API groups (`sparql` and `graphStore`) for the API at
+ * the options' paths, using the server's services from the context.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerHandlers = (options?: ApiOptions) => {
+  const resolved = serverOptions(options);
+  return handlersFor(SparqlApi.make(resolved), resolved);
+};
+
+/**
+ * The `SparqlApi.SchemaFallback` middleware: a request whose parameters or
+ * headers fail the API's schemas is answered by `SparqlServer.handler`, so
+ * it gets the protocol's own status and message (e.g. `400` "Exactly one
+ * 'query' parameter is allowed"). Response encoding failures stay `500`.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerSchemaFallback = (
+  options?: ApiOptions,
+): Layer.Layer<SparqlApi.SchemaFallback> => {
+  const app = SparqlServer.handler(serverOptions(options));
+  return HttpApiMiddleware.layerSchemaErrorTransform(SparqlApi.SchemaFallback, (error) =>
+    error.kind === 'Body' || error.kind === 'ResponseHeaders' ? Effect.fail(error) : app,
+  );
+};
+
+/**
+ * The fallback routes: every method on `<path>*` and `<graphStorePath>*`
+ * that the API does not declare, answered by `SparqlServer.handler` (`405`
+ * with `Allow`, CORS preflights, direct graph identification, `404` for
+ * other paths).
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerFallback = (
+  options?: ApiOptions,
+): Layer.Layer<
+  never,
+  never,
+  HttpRouter.HttpRouter | HttpRouter.Request.From<'Requires', SparqlServer.Requirements>
+> => {
+  const resolved = serverOptions(options);
+  const app = SparqlServer.handler(resolved);
+  return HttpRouter.use((router) =>
+    Effect.gen(function* () {
+      // A wildcard right after the path matches the path itself (for methods the API does not
+      // declare) and everything below it, without clashing with the API's own routes.
+      yield* router.add('*', `${resolved.path}*`, app);
+      yield* router.add('*', `${resolved.graphStorePath}*`, app);
+    }),
+  );
+};
+
+/**
+ * Registers the API on the `HttpRouter`: the `HttpApiBuilder` routes with
+ * their handlers and the `SchemaFallback` middleware, the fallback routes and, with `openapiPath`, the OpenAPI
+ * document.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerRoutes = (options?: ApiOptions) => {
+  const resolved = serverOptions(options);
+  const api = SparqlApi.make(resolved);
+  const schemaFallback = layerSchemaFallback(options);
+  return Layer.mergeAll(
+    HttpApiBuilder.layer(api, { openapiPath: options?.openapiPath }).pipe(
+      Layer.provide(handlersFor(api, resolved).pipe(Layer.provide(schemaFallback))),
+    ),
+    layerFallback(options),
+  );
+};
+
+/**
+ * Serves the API routes with `HttpRouter.serve` on an `HttpServer` from the
+ * context (logging requests unless `logging: false`); the server layer (such
+ * as `NodeHttpServer.layer`) also provides the platform services
+ * `HttpApiBuilder` needs.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerServe = (options?: ApiOptions) =>
+  HttpRouter.serve(layerRoutes({ ...options, logging: false }), {
+    disableLogger: options?.logging === false,
+  });
+
+/**
+ * In-process testing: builds a client for the `SparqlApi` routes
+ * (`layerRoutes(options)`) using the server's services from
+ * the context. The routes live as long as the surrounding scope.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const makeTestClient = (
+  options?: ApiOptions,
+): Effect.Effect<HttpClient.HttpClient, never, SparqlServer.Requirements | Scope.Scope> =>
+  Effect.gen(function* () {
+    const scope = yield* Scope.Scope;
+    const context = yield* Effect.context<SparqlServer.Requirements>();
+    const app = yield* HttpRouter.toHttpEffect(
+      layerRoutes(options).pipe(Layer.provide(HttpServer.layerServices)),
+    );
+    return Testing.fromApp(
+      app.pipe(
+        Effect.catchCause((cause) =>
+          Effect.map(HttpServerError.causeResponse(cause), ([response]) => response),
+        ),
+        Effect.provideService(Scope.Scope, scope),
+        Effect.provideContext(context),
+      ),
+    );
+  });