@satorio/machinery 0.2.1

package/dist/queue/settings.d.ts

@@ -0,0 +1,106 @@
+import { type EnvironmentEntry, type Refusal } from '@satorio/machinery/core';
+import { Config, Option } from 'effect';
+/**
+ * The most messages SQS hands back from one receive call. The service
+ * asks for no more than this, because SQS returns no more than this.
+ *
+ * @internal
+ */
+export declare const SQS_HIGHEST_MESSAGES_PER_RECEIVE = 10;
+/**
+ * The longest long poll SQS allows. Anything above it is a value SQS
+ * itself refuses.
+ *
+ * @internal
+ */
+export declare const SQS_HIGHEST_WAIT_TIME_SECONDS = 20;
+/**
+ * The longest SQS keeps a received message hidden from other consumers:
+ * twelve hours.
+ *
+ * @internal
+ */
+export declare const SQS_HIGHEST_VISIBILITY_TIMEOUT_SECONDS = 43200;
+/**
+ * How long a received message stays hidden while a handler works on it,
+ * when nobody names a number. A minute is long enough for an ordinary
+ * handler and short enough that a crashed one redelivers soon.
+ */
+export declare const SQS_DEFAULT_VISIBILITY_TIMEOUT_SECONDS = 60;
+/**
+ * Builds the environment variable name from the prefix the application
+ * gives at mount time. One process serves any number of queues this way,
+ * with readable names: `INBOUND_QUEUE_URL`, `RETRY_QUEUE_URL`, and so on.
+ */
+export declare const queueUrlVariable: (variablePrefix: string) => string;
+/**
+ * What a consumer needs before it can receive a single message.
+ *
+ * What a consumer needs before it can receive: the queue to poll, how it
+ * polls, and the two variables the AWS SDK reads for itself when nobody names
+ * them.
+ */
+export interface QueueConsumerSettings {
+    readonly queueUrl: string;
+    readonly maxMessagesPerReceive: number;
+    readonly waitTimeSeconds: number;
+    readonly visibilityTimeoutSeconds: number;
+    readonly region: Option.Option<string>;
+    readonly endpoint: Option.Option<string>;
+}
+/**
+ * What a producer needs before it can send: the queue, and the same two
+ * variables the SDK decides for itself.
+ */
+export interface QueueProducerSettings {
+    readonly queueUrl: string;
+    readonly region: Option.Option<string>;
+    readonly endpoint: Option.Option<string>;
+}
+/**
+ * The three parts a reader meets when the queue URL is not set. The
+ * mount desk logs this text and every operation of the loud stub fails
+ * with it, so an operator reads one sentence rather than two.
+ *
+ * @internal
+ */
+export declare const queueUrlRefusal: (variablePrefix: string) => Refusal;
+/**
+ * Reads the queue URL without refusing, so the mount desk can put up the
+ * loud stub instead of failing service startup.
+ *
+ * @internal
+ */
+export declare const configuredQueueUrl: (variablePrefix: string) => Config.Config<Option.Option<string>>;
+/**
+ * Every variable this adapter reads, and the one state each of them
+ * stands in. `<PREFIX>` is the prefix the application passes at mount
+ * time; the three poll settings share that prefix and keep their own
+ * suffixes.
+ */
+export declare const ENVIRONMENT: readonly EnvironmentEntry[];
+/**
+ * Reads every variable a consumer needs under one prefix. A missing or
+ * blank queue URL refuses in three parts; the three poll settings fall
+ * back to their defaults; region and endpoint stay `Option.none`, and
+ * the SDK decides.
+ */
+export declare const queueConsumerSettings: (variablePrefix: string) => Config.Config<QueueConsumerSettings>;
+/**
+ * Reads every variable a producer needs under one prefix. A producer
+ * only sends, so it reads the queue URL and nothing about polling.
+ */
+export declare const queueProducerSettings: (variablePrefix: string) => Config.Config<QueueProducerSettings>;
+/**
+ * The client configuration shape both transports and the readiness probe
+ * share: region and endpoint appear in it only when they are set.
+ *
+ * @internal
+ */
+export declare const sqsClientConfigurationOf: (settings: {
+    readonly region: Option.Option<string>;
+    readonly endpoint: Option.Option<string>;
+}) => {
+    readonly region?: string;
+    readonly endpoint?: string;
+};

package/dist/queue/settings.js

@@ -0,0 +1,160 @@
+import { fallsBackTo, handedOn, optionalText, refuses, requiredText, wholeNumberFallingBackTo, } from '@satorio/machinery/core';
+import { Config, Option } from 'effect';
+const QUEUE_URL_SUFFIX = '_QUEUE_URL';
+const MAX_MESSAGES_SUFFIX = '_MAX_MESSAGES_PER_RECEIVE';
+const WAIT_TIME_SUFFIX = '_WAIT_TIME_SECONDS';
+const VISIBILITY_TIMEOUT_SUFFIX = '_VISIBILITY_TIMEOUT_SECONDS';
+const REGION = 'AWS_REGION';
+const ENDPOINT = 'AWS_ENDPOINT_URL';
+const LOWEST = 1;
+/**
+ * The most messages SQS hands back from one receive call. The service
+ * asks for no more than this, because SQS returns no more than this.
+ *
+ * @internal
+ */
+export const SQS_HIGHEST_MESSAGES_PER_RECEIVE = 10;
+/**
+ * The longest long poll SQS allows. Anything above it is a value SQS
+ * itself refuses.
+ *
+ * @internal
+ */
+export const SQS_HIGHEST_WAIT_TIME_SECONDS = 20;
+/**
+ * The longest SQS keeps a received message hidden from other consumers:
+ * twelve hours.
+ *
+ * @internal
+ */
+export const SQS_HIGHEST_VISIBILITY_TIMEOUT_SECONDS = 43_200;
+/**
+ * How long a received message stays hidden while a handler works on it,
+ * when nobody names a number. A minute is long enough for an ordinary
+ * handler and short enough that a crashed one redelivers soon.
+ */
+export const SQS_DEFAULT_VISIBILITY_TIMEOUT_SECONDS = 60;
+/**
+ * Builds the environment variable name from the prefix the application
+ * gives at mount time. One process serves any number of queues this way,
+ * with readable names: `INBOUND_QUEUE_URL`, `RETRY_QUEUE_URL`, and so on.
+ */
+export const queueUrlVariable = (variablePrefix) => `${variablePrefix}${QUEUE_URL_SUFFIX}`;
+/**
+ * The three parts a reader meets when the queue URL is not set. The
+ * mount desk logs this text and every operation of the loud stub fails
+ * with it, so an operator reads one sentence rather than two.
+ *
+ * @internal
+ */
+export const queueUrlRefusal = (variablePrefix) => ({
+    what: `${queueUrlVariable(variablePrefix)} is not set, so this queue has no address.`,
+    why: 'One process serves several queues, each under its own prefix, so the machinery cannot guess which one you meant.',
+    whatToDo: `Set ${queueUrlVariable(variablePrefix)} to the full queue URL from the AWS console or your .env, then start the service again.`,
+});
+const rangeRefusal = (name, what, highest) => ({
+    what: `${name} is set to something this consumer cannot poll with.`,
+    why: `${what} It has to be a whole number from ${LOWEST} to ${highest}, which is the range SQS itself accepts.`,
+    whatToDo: `Set ${name} to a whole number from ${LOWEST} to ${highest}, or leave it unset and take the default.`,
+});
+/**
+ * Reads the queue URL without refusing, so the mount desk can put up the
+ * loud stub instead of failing service startup.
+ *
+ * @internal
+ */
+export const configuredQueueUrl = (variablePrefix) => optionalText(queueUrlVariable(variablePrefix));
+/**
+ * Every variable this adapter reads, and the one state each of them
+ * stands in. `<PREFIX>` is the prefix the application passes at mount
+ * time; the three poll settings share that prefix and keep their own
+ * suffixes.
+ */
+export const ENVIRONMENT = [
+    {
+        name: QUEUE_URL_SUFFIX,
+        prefixed: true,
+        what: 'The queue a consumer receives from and a producer sends to.',
+        state: refuses(queueUrlRefusal('<PREFIX>')),
+    },
+    {
+        name: MAX_MESSAGES_SUFFIX,
+        prefixed: true,
+        what: 'How many messages one receive call asks for.',
+        state: fallsBackTo(String(SQS_HIGHEST_MESSAGES_PER_RECEIVE)),
+    },
+    {
+        name: WAIT_TIME_SUFFIX,
+        prefixed: true,
+        what: 'How many seconds a receive call waits for a message before it comes back empty.',
+        state: fallsBackTo(String(SQS_HIGHEST_WAIT_TIME_SECONDS)),
+    },
+    {
+        name: VISIBILITY_TIMEOUT_SUFFIX,
+        prefixed: true,
+        what: 'How many seconds a received message stays hidden from other consumers.',
+        state: fallsBackTo(String(SQS_DEFAULT_VISIBILITY_TIMEOUT_SECONDS)),
+    },
+    {
+        name: REGION,
+        what: 'The region the SQS client talks to.',
+        state: handedOn('the AWS SDK finds its own region from the machine it runs on.'),
+    },
+    {
+        name: ENDPOINT,
+        what: 'A local stand to talk to instead of real SQS, such as localstack.',
+        state: handedOn('the client goes to the real SQS for the region it found.'),
+    },
+];
+const queueUrl = (variablePrefix) => requiredText(queueUrlVariable(variablePrefix), queueUrlRefusal(variablePrefix));
+const maxMessagesPerReceive = (variablePrefix) => {
+    const name = `${variablePrefix}${MAX_MESSAGES_SUFFIX}`;
+    return wholeNumberFallingBackTo(name, LOWEST, SQS_HIGHEST_MESSAGES_PER_RECEIVE, SQS_HIGHEST_MESSAGES_PER_RECEIVE, rangeRefusal(name, 'It says how many messages one receive call asks for.', SQS_HIGHEST_MESSAGES_PER_RECEIVE));
+};
+const waitTimeSeconds = (variablePrefix) => {
+    const name = `${variablePrefix}${WAIT_TIME_SUFFIX}`;
+    return wholeNumberFallingBackTo(name, LOWEST, SQS_HIGHEST_WAIT_TIME_SECONDS, SQS_HIGHEST_WAIT_TIME_SECONDS, rangeRefusal(name, 'Zero turns long polling off and makes the consumer a hot loop.', SQS_HIGHEST_WAIT_TIME_SECONDS));
+};
+const visibilityTimeoutSeconds = (variablePrefix) => {
+    const name = `${variablePrefix}${VISIBILITY_TIMEOUT_SUFFIX}`;
+    return wholeNumberFallingBackTo(name, LOWEST, SQS_HIGHEST_VISIBILITY_TIMEOUT_SECONDS, SQS_DEFAULT_VISIBILITY_TIMEOUT_SECONDS, rangeRefusal(name, 'It says how long a handler has before the message comes back to another consumer.', SQS_HIGHEST_VISIBILITY_TIMEOUT_SECONDS));
+};
+/**
+ * Reads every variable a consumer needs under one prefix. A missing or
+ * blank queue URL refuses in three parts; the three poll settings fall
+ * back to their defaults; region and endpoint stay `Option.none`, and
+ * the SDK decides.
+ */
+export const queueConsumerSettings = (variablePrefix) => Config.all({
+    queueUrl: queueUrl(variablePrefix),
+    maxMessagesPerReceive: maxMessagesPerReceive(variablePrefix),
+    waitTimeSeconds: waitTimeSeconds(variablePrefix),
+    visibilityTimeoutSeconds: visibilityTimeoutSeconds(variablePrefix),
+    region: optionalText(REGION),
+    endpoint: optionalText(ENDPOINT),
+});
+/**
+ * Reads every variable a producer needs under one prefix. A producer
+ * only sends, so it reads the queue URL and nothing about polling.
+ */
+export const queueProducerSettings = (variablePrefix) => Config.all({
+    queueUrl: queueUrl(variablePrefix),
+    region: optionalText(REGION),
+    endpoint: optionalText(ENDPOINT),
+});
+/**
+ * The client configuration shape both transports and the readiness probe
+ * share: region and endpoint appear in it only when they are set.
+ *
+ * @internal
+ */
+export const sqsClientConfigurationOf = (settings) => ({
+    ...Option.match(settings.region, {
+        onNone: () => ({}),
+        onSome: (region) => ({ region }),
+    }),
+    ...Option.match(settings.endpoint, {
+        onNone: () => ({}),
+        onSome: (endpoint) => ({ endpoint }),
+    }),
+});

package/dist/storage/blob-store.d.ts

@@ -0,0 +1,84 @@
+import { type Refusal } from '@satorio/machinery/core';
+import { type BlobStoreShape } from '@satorio/machinery/ports';
+import { Effect, type Scope } from 'effect';
+import type { BlobStoreSettings } from './settings.js';
+/**
+ * The narrowest slice of the SDK the store uses: put, get, check
+ * existence, delete. A test can substitute its own object of this shape
+ * without a network or a mock of the whole client.
+ */
+export interface S3PutRequest {
+    readonly Bucket: string;
+    readonly Key: string;
+    readonly Body: Uint8Array;
+    readonly ContentType: string;
+    readonly Metadata: Readonly<Record<string, string>>;
+}
+/**
+ * One object named: the bucket it sits in and the key it sits under.
+ */
+export interface S3KeyRequest {
+    readonly Bucket: string;
+    readonly Key: string;
+}
+/**
+ * One object as the store hands it back: its bytes, and the content type and
+ * metadata it carries when it carries any.
+ */
+export interface S3FetchedObject {
+    readonly body: Uint8Array;
+    readonly contentType: string | undefined;
+    readonly metadata: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * The narrow slice of the object store a blob store calls: put, get, check,
+ * delete, and nothing else.
+ */
+export interface S3ObjectTransport {
+    readonly putObject: (request: S3PutRequest, signal?: AbortSignal) => Promise<unknown>;
+    readonly getObject: (request: S3KeyRequest, signal?: AbortSignal) => Promise<S3FetchedObject>;
+    readonly headObject: (request: S3KeyRequest, signal?: AbortSignal) => Promise<unknown>;
+    readonly deleteObject: (request: S3KeyRequest, signal?: AbortSignal) => Promise<unknown>;
+}
+/**
+ * A transport that also closes, so the client behind it is released when the
+ * scope around it ends.
+ */
+export interface ClosableS3Transport extends S3ObjectTransport {
+    readonly close: () => void;
+}
+/**
+ * S3 signals "no such key" as an ERROR, not an empty response: `GetObject`
+ * throws `NoSuchKey`, `HeadObject` throws `NotFound`. The port is more
+ * honest than the SDK: absence is `Option.none` and `false`, not a failure.
+ */
+export declare const signalsAbsentKey: (error: unknown) => boolean;
+/**
+ * What an object is read as when the store hands back no content type of its
+ * own: plain bytes.
+ */
+export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/**
+ * Builds the blob store over one transport and one bucket, turning the store's
+ * own way of signalling a missing key into an absent value.
+ */
+export declare const makeS3BlobStore: (transport: S3ObjectTransport, settings: BlobStoreSettings) => BlobStoreShape;
+/**
+ * Opens a transport that closes with the scope around it, so no client
+ * outlives the work that opened it.
+ */
+export declare const scopedS3Transport: (openTransport: () => ClosableS3Transport) => Effect.Effect<S3ObjectTransport, never, Scope.Scope>;
+/**
+ * Opens the real object-store client against the settings handed in, and is
+ * the one place that client is constructed.
+ */
+export declare const openS3Transport: (settings: BlobStoreSettings) => ClosableS3Transport;
+/**
+ * Without a bucket set, the store does not fail service startup: it mounts
+ * a stub that fails every operation loudly. The rest of the service keeps
+ * running, and the use case reports the missing configuration honestly
+ * instead of silently losing what it stored. The stub carries the same
+ * `Refusal` the mount desk logs, so the operator reads one text on both
+ * paths.
+ */
+export declare const blobStoreUnavailableWithoutConfiguration: (refusal: Refusal) => BlobStoreShape;

package/dist/storage/blob-store.js

@@ -0,0 +1,109 @@
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client, } from '@aws-sdk/client-s3';
+import { refusalText } from '@satorio/machinery/core';
+import { BlobStoreUnavailableError, } from '@satorio/machinery/ports';
+import { Effect, Option } from 'effect';
+/**
+ * S3 signals "no such key" as an ERROR, not an empty response: `GetObject`
+ * throws `NoSuchKey`, `HeadObject` throws `NotFound`. The port is more
+ * honest than the SDK: absence is `Option.none` and `false`, not a failure.
+ */
+export const signalsAbsentKey = (error) => error instanceof Error &&
+    (error.name === 'NoSuchKey' || error.name === 'NotFound');
+/**
+ * What an object is read as when the store hands back no content type of its
+ * own: plain bytes.
+ */
+export const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+const storedBlobOf = (fetched) => ({
+    body: fetched.body,
+    contentType: fetched.contentType ?? DEFAULT_CONTENT_TYPE,
+    metadata: fetched.metadata ?? {},
+});
+/**
+ * Builds the blob store over one transport and one bucket, turning the store's
+ * own way of signalling a missing key into an absent value.
+ */
+export const makeS3BlobStore = (transport, settings) => ({
+    put: (key, blob) => Effect.tryPromise({
+        try: (signal) => transport.putObject({
+            Bucket: settings.bucket,
+            Key: key,
+            Body: blob.body,
+            ContentType: blob.contentType,
+            Metadata: blob.metadata,
+        }, signal),
+        catch: (cause) => new BlobStoreUnavailableError({ operation: 'put', cause }),
+    }).pipe(Effect.asVoid),
+    get: (key) => Effect.tryPromise({
+        try: (signal) => transport.getObject({ Bucket: settings.bucket, Key: key }, signal),
+        catch: (cause) => new BlobStoreUnavailableError({ operation: 'get', cause }),
+    }).pipe(Effect.map((fetched) => Option.some(storedBlobOf(fetched))), Effect.catchIf((error) => signalsAbsentKey(error.cause), () => Effect.succeed(Option.none()))),
+    exists: (key) => Effect.tryPromise({
+        try: (signal) => transport.headObject({ Bucket: settings.bucket, Key: key }, signal),
+        catch: (cause) => new BlobStoreUnavailableError({ operation: 'exists', cause }),
+    }).pipe(Effect.as(true), Effect.catchIf((error) => signalsAbsentKey(error.cause), () => Effect.succeed(false))),
+    delete: (key) => Effect.tryPromise({
+        try: (signal) => transport.deleteObject({ Bucket: settings.bucket, Key: key }, signal),
+        catch: (cause) => new BlobStoreUnavailableError({ operation: 'delete', cause }),
+    }).pipe(Effect.asVoid),
+});
+/**
+ * Opens a transport that closes with the scope around it, so no client
+ * outlives the work that opened it.
+ */
+export const scopedS3Transport = (openTransport) => Effect.acquireRelease(Effect.sync(openTransport), (transport) => Effect.sync(() => transport.close()));
+const clientConfigurationOf = (settings) => ({
+    ...Option.match(settings.region, {
+        onNone: () => ({}),
+        onSome: (region) => ({ region }),
+    }),
+    ...Option.match(settings.endpoint, {
+        onNone: () => ({}),
+        onSome: (endpoint) => ({ endpoint, forcePathStyle: true }),
+    }),
+});
+const abortOptions = (signal) => signal === undefined ? {} : { abortSignal: signal };
+/**
+ * Opens the real object-store client against the settings handed in, and is
+ * the one place that client is constructed.
+ */
+export const openS3Transport = (settings) => {
+    const client = new S3Client(clientConfigurationOf(settings));
+    return {
+        putObject: (request, signal) => client.send(new PutObjectCommand(request), abortOptions(signal)),
+        getObject: async (request, signal) => {
+            const result = await client.send(new GetObjectCommand(request), abortOptions(signal));
+            if (result.Body === undefined) {
+                throw new Error('S3 returned an object without a body');
+            }
+            return {
+                body: await result.Body.transformToByteArray(),
+                contentType: result.ContentType,
+                metadata: result.Metadata,
+            };
+        },
+        headObject: (request, signal) => client.send(new HeadObjectCommand(request), abortOptions(signal)),
+        deleteObject: (request, signal) => client.send(new DeleteObjectCommand(request), abortOptions(signal)),
+        close: () => client.destroy(),
+    };
+};
+/**
+ * Without a bucket set, the store does not fail service startup: it mounts
+ * a stub that fails every operation loudly. The rest of the service keeps
+ * running, and the use case reports the missing configuration honestly
+ * instead of silently losing what it stored. The stub carries the same
+ * `Refusal` the mount desk logs, so the operator reads one text on both
+ * paths.
+ */
+export const blobStoreUnavailableWithoutConfiguration = (refusal) => {
+    const failure = (operation) => new BlobStoreUnavailableError({
+        operation,
+        cause: refusalText(refusal),
+    });
+    return {
+        put: () => failure('put'),
+        get: () => failure('get'),
+        exists: () => failure('exists'),
+        delete: () => failure('delete'),
+    };
+};

package/dist/storage/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public entry to the storage mechanism: whole objects stored under a key and
+ * read back. It gives you the `BlobStore` port bound to S3, with the bucket
+ * read from one prefixed variable and a loud stub in its place when nobody set
+ * it.
+ */
+export { blobStoreUnavailableWithoutConfiguration, type ClosableS3Transport, DEFAULT_CONTENT_TYPE, makeS3BlobStore, openS3Transport, type S3FetchedObject, type S3KeyRequest, type S3ObjectTransport, type S3PutRequest, scopedS3Transport, signalsAbsentKey, } from './blob-store.js';
+export { blobStoreFromEnvironmentLive, s3BlobStoreLive } from './layer.js';
+export { type BlobStoreSettings, blobStoreSettings, bucketVariable, ENVIRONMENT, } from './settings.js';

package/dist/storage/index.js

@@ -0,0 +1,9 @@
+/**
+ * Public entry to the storage mechanism: whole objects stored under a key and
+ * read back. It gives you the `BlobStore` port bound to S3, with the bucket
+ * read from one prefixed variable and a loud stub in its place when nobody set
+ * it.
+ */
+export { blobStoreUnavailableWithoutConfiguration, DEFAULT_CONTENT_TYPE, makeS3BlobStore, openS3Transport, scopedS3Transport, signalsAbsentKey, } from './blob-store.js';
+export { blobStoreFromEnvironmentLive, s3BlobStoreLive } from './layer.js';
+export { blobStoreSettings, bucketVariable, ENVIRONMENT, } from './settings.js';

package/dist/storage/layer.d.ts

@@ -0,0 +1,17 @@
+import { BlobStore } from '@satorio/machinery/ports';
+import { type ConfigError, Layer } from 'effect';
+import { type ClosableS3Transport } from './blob-store.js';
+import { type BlobStoreSettings } from './settings.js';
+/**
+ * A blob store built from environment variables with the given prefix.
+ * With no bucket set it mounts the loud stub and logs the one refusal
+ * every later operation repeats, so startup carries on and nothing goes
+ * missing in silence. The transport is a parameter, so a test
+ * substitutes its own without touching the wiring.
+ */
+export declare const blobStoreFromEnvironmentLive: (variablePrefix: string, openTransport: (settings: BlobStoreSettings) => ClosableS3Transport) => Layer.Layer<BlobStore, ConfigError.ConfigError>;
+/**
+ * The blob store on the real AWS SDK transport, reading the variables
+ * this prefix names.
+ */
+export declare const s3BlobStoreLive: (variablePrefix: string) => Layer.Layer<BlobStore, ConfigError.ConfigError>;

package/dist/storage/layer.js

@@ -0,0 +1,30 @@
+import { refusalText } from '@satorio/machinery/core';
+import { BlobStore } from '@satorio/machinery/ports';
+import { Effect, Layer, Option } from 'effect';
+import { blobStoreUnavailableWithoutConfiguration, makeS3BlobStore, openS3Transport, scopedS3Transport, } from './blob-store.js';
+import { blobStoreSettings, bucketRefusal, configuredBucket, } from './settings.js';
+/**
+ * A blob store built from environment variables with the given prefix.
+ * With no bucket set it mounts the loud stub and logs the one refusal
+ * every later operation repeats, so startup carries on and nothing goes
+ * missing in silence. The transport is a parameter, so a test
+ * substitutes its own without touching the wiring.
+ */
+export const blobStoreFromEnvironmentLive = (variablePrefix, openTransport) => Layer.unwrapEffect(Effect.gen(function* () {
+    const configured = yield* configuredBucket(variablePrefix);
+    if (Option.isNone(configured)) {
+        const refusal = bucketRefusal(variablePrefix);
+        yield* Effect.logError(refusalText(refusal));
+        return Layer.succeed(BlobStore, blobStoreUnavailableWithoutConfiguration(refusal));
+    }
+    return Layer.scoped(BlobStore, Effect.gen(function* () {
+        const settings = yield* blobStoreSettings(variablePrefix);
+        const transport = yield* scopedS3Transport(() => openTransport(settings));
+        return makeS3BlobStore(transport, settings);
+    }));
+}));
+/**
+ * The blob store on the real AWS SDK transport, reading the variables
+ * this prefix names.
+ */
+export const s3BlobStoreLive = (variablePrefix) => blobStoreFromEnvironmentLive(variablePrefix, openS3Transport);

package/dist/storage/settings.d.ts

@@ -0,0 +1,48 @@
+import { type EnvironmentEntry, type Refusal } from '@satorio/machinery/core';
+import { Config, type Option } from 'effect';
+/**
+ * Builds the environment variable name from the prefix the application
+ * gives at mount time. One machinery instance serves any number of buckets
+ * in one process this way, with readable names: `MEDIA_BUCKET`,
+ * `REPORTS_BUCKET`, and so on.
+ */
+export declare const bucketVariable: (variablePrefix: string) => string;
+/**
+ * What the store needs before it can talk to the object store.
+ *
+ * What the store needs before it can talk to S3: one bucket, and the two
+ * variables the AWS SDK reads for itself when nobody names them.
+ */
+export interface BlobStoreSettings {
+    readonly bucket: string;
+    readonly region: Option.Option<string>;
+    readonly endpoint: Option.Option<string>;
+}
+/**
+ * The three parts a reader meets when the bucket is not set: what
+ * happened, why the store cannot go on, and what to do next. The mount
+ * desk logs this text and every operation of the loud stub fails with
+ * it, so an operator reads one sentence rather than two.
+ *
+ * @internal
+ */
+export declare const bucketRefusal: (variablePrefix: string) => Refusal;
+/**
+ * Reads the bucket without refusing, so the mount desk can put up the
+ * loud stub instead of failing service startup.
+ *
+ * @internal
+ */
+export declare const configuredBucket: (variablePrefix: string) => Config.Config<Option.Option<string>>;
+/**
+ * Every variable this adapter reads, and the one state each of them
+ * stands in. `<PREFIX>` is the prefix the application passes at mount
+ * time.
+ */
+export declare const ENVIRONMENT: readonly EnvironmentEntry[];
+/**
+ * Reads every variable of `ENVIRONMENT` under one prefix. A missing or
+ * blank bucket refuses in three parts; region and endpoint stay
+ * `Option.none`, and the SDK decides.
+ */
+export declare const blobStoreSettings: (variablePrefix: string) => Config.Config<BlobStoreSettings>;

package/dist/storage/settings.js

@@ -0,0 +1,65 @@
+import { handedOn, optionalText, refuses, requiredText, } from '@satorio/machinery/core';
+import { Config } from 'effect';
+const BUCKET_SUFFIX = '_BUCKET';
+const REGION = 'AWS_REGION';
+const ENDPOINT = 'AWS_ENDPOINT_URL';
+/**
+ * Builds the environment variable name from the prefix the application
+ * gives at mount time. One machinery instance serves any number of buckets
+ * in one process this way, with readable names: `MEDIA_BUCKET`,
+ * `REPORTS_BUCKET`, and so on.
+ */
+export const bucketVariable = (variablePrefix) => `${variablePrefix}${BUCKET_SUFFIX}`;
+/**
+ * The three parts a reader meets when the bucket is not set: what
+ * happened, why the store cannot go on, and what to do next. The mount
+ * desk logs this text and every operation of the loud stub fails with
+ * it, so an operator reads one sentence rather than two.
+ *
+ * @internal
+ */
+export const bucketRefusal = (variablePrefix) => ({
+    what: `${bucketVariable(variablePrefix)} is not set, so this object store has no bucket.`,
+    why: 'One process serves several buckets, each under its own prefix, so the store cannot guess which one you meant.',
+    whatToDo: `Set ${bucketVariable(variablePrefix)} to the bucket name from the AWS console or your .env, then start the service again.`,
+});
+/**
+ * Reads the bucket without refusing, so the mount desk can put up the
+ * loud stub instead of failing service startup.
+ *
+ * @internal
+ */
+export const configuredBucket = (variablePrefix) => optionalText(bucketVariable(variablePrefix));
+/**
+ * Every variable this adapter reads, and the one state each of them
+ * stands in. `<PREFIX>` is the prefix the application passes at mount
+ * time.
+ */
+export const ENVIRONMENT = [
+    {
+        name: BUCKET_SUFFIX,
+        prefixed: true,
+        what: 'The bucket this store puts objects into and reads them back from.',
+        state: refuses(bucketRefusal('<PREFIX>')),
+    },
+    {
+        name: REGION,
+        what: 'The region the S3 client talks to.',
+        state: handedOn('the AWS SDK finds its own region from the machine it runs on.'),
+    },
+    {
+        name: ENDPOINT,
+        what: 'A local stand to talk to instead of real S3, such as localstack.',
+        state: handedOn('the client goes to the real S3 for the region it found.'),
+    },
+];
+/**
+ * Reads every variable of `ENVIRONMENT` under one prefix. A missing or
+ * blank bucket refuses in three parts; region and endpoint stay
+ * `Option.none`, and the SDK decides.
+ */
+export const blobStoreSettings = (variablePrefix) => Config.all({
+    bucket: requiredText(bucketVariable(variablePrefix), bucketRefusal(variablePrefix)),
+    region: optionalText(REGION),
+    endpoint: optionalText(ENDPOINT),
+});

package/dist/testing/blob-store.d.ts

@@ -0,0 +1,27 @@
+import { BlobStore, type BlobStoreShape, type StoredBlob } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+/**
+ * What an in-memory blob store holds: every blob it was given, by key. A
+ * scenario keeps the `Ref` and reads this map to see what a use case
+ * stored.
+ */
+export type BlobsByKey = ReadonlyMap<string, StoredBlob>;
+/**
+ * An in-memory blob store over a `Ref` you keep, so a test can seed it
+ * before the run and read it after.
+ */
+export declare const makeInMemoryBlobStoreWith: (blobs: Ref.Ref<BlobsByKey>) => BlobStoreShape;
+/**
+ * An in-memory blob store over a `Ref` of its own, empty at the start.
+ */
+export declare const makeInMemoryBlobStore: Effect.Effect<BlobStoreShape, never, never>;
+/**
+ * The in-memory blob store, mounted.
+ */
+export declare const InMemoryBlobStoreLive: Layer.Layer<BlobStore, never, never>;
+/**
+ * A blob store that answers nothing: every operation fails with
+ * `BlobStoreUnavailableError`. Mount it to walk the branch a working
+ * stand-in never reaches.
+ */
+export declare const BlobStoreUnavailableLive: Layer.Layer<BlobStore>;