@bjornpagen/bumbledb 1.3.1 → 2.0.0

package/src/database/driver.ts

@@ -0,0 +1,134 @@
+/**
+ * Drives one sans-IO log machine. Requests and store responses go through one mailbox, so the
+ * machine steps strictly one input at a time; every `IoRequest` a step emits runs concurrently
+ * (bounded) and comes back as another input. Each request carries a ticket that settles exactly
+ * once, and closing the driver settles every ticket still open.
+ */
+import type { Scope } from "effect"
+import { Deferred, Effect, Fiber, FiberSet, Queue, Semaphore } from "effect"
+import { DbError } from "../errors.ts"
+import type { ExecutorOptions, IoRequest, IoResponse, ObjectStore } from "./io.ts"
+import { defaultExecutorOptions, execute } from "./io.ts"
+
+interface Step<Settled> {
+	readonly io: readonly IoRequest[]
+	readonly done: ReadonlyArray<{ readonly ticket: bigint; readonly settled: Settled }>
+}
+
+/** The machine as the driver sees it. The driver never calls it concurrently. */
+interface MachinePort<Request, Settled> {
+	readonly request: (ticket: bigint, request: Request) => Effect.Effect<Step<Settled>, DbError>
+	readonly respond: (response: IoResponse) => Effect.Effect<Step<Settled>, DbError>
+	/** Stops the machine; its step settles every open ticket. */
+	readonly close: Effect.Effect<Step<Settled>, DbError>
+}
+
+interface DriverOptions {
+	/** Store calls in flight at once. */
+	readonly concurrency: number
+	readonly executor: ExecutorOptions
+}
+
+interface Driver<Request, Settled> {
+	/** Submits one request and waits for its settlement. */
+	readonly run: (request: Request) => Effect.Effect<Settled, DbError>
+}
+
+type Message<Request> =
+	| { readonly _tag: "Request"; readonly ticket: bigint; readonly request: Request }
+	| { readonly _tag: "Response"; readonly response: IoResponse }
+	| { readonly _tag: "Close" }
+
+const defaultDriverOptions: DriverOptions = { concurrency: 32, executor: defaultExecutorOptions }
+
+/** Starts a driver owned by the current scope; closing the scope closes the machine. */
+const make = Effect.fnUntraced(function* <Request, Settled>(
+	port: MachinePort<Request, Settled>,
+	store: ObjectStore,
+	options: DriverOptions = defaultDriverOptions
+): Effect.fn.Return<Driver<Request, Settled>, never, Scope.Scope> {
+	const mailbox = yield* Queue.unbounded<Message<Request>>()
+	const permits = yield* Semaphore.make(options.concurrency)
+	const io = yield* FiberSet.make()
+	const tickets = new Map<bigint, Deferred.Deferred<Settled, DbError>>()
+	let nextTicket = 0n
+	const closed = new DbError({ operation: "Database", reason: { _tag: "ClosedHandle" } })
+
+	const apply = (step: Step<Settled>) =>
+		Effect.gen(function* () {
+			for (const { ticket, settled } of step.done) {
+				const waiter = tickets.get(ticket)
+				tickets.delete(ticket)
+				if (waiter !== undefined) yield* Deferred.succeed(waiter, settled)
+			}
+			for (const request of step.io) {
+				yield* FiberSet.run(
+					io,
+					Semaphore.withPermit(permits, execute(store, request, options.executor)).pipe(
+						Effect.flatMap((response) => Queue.offer(mailbox, { _tag: "Response", response }))
+					)
+				)
+			}
+		})
+
+	let stopped: DbError | undefined
+
+	/** Ends the driver: later runs fail with `error`, and open tickets fail with it now. */
+	const stop = (error: DbError) =>
+		Effect.suspend(() => {
+			stopped ??= error
+			const open = [...tickets.values()]
+			tickets.clear()
+			return Effect.forEach(open, (waiter) => Deferred.fail(waiter, error), { discard: true })
+		})
+
+	const stepFor = (message: Message<Request>) => {
+		switch (message._tag) {
+			case "Request":
+				return port.request(message.ticket, message.request)
+			case "Response":
+				return port.respond(message.response)
+			case "Close":
+				return port.close
+		}
+	}
+
+	const loop: Effect.Effect<void> = Effect.gen(function* () {
+		while (true) {
+			const message = yield* Queue.take(mailbox)
+			const step = stepFor(message)
+			const failed = yield* step.pipe(
+				Effect.flatMap(apply),
+				Effect.as(false),
+				Effect.catch((error) => Effect.as(stop(error), true))
+			)
+			if (failed || message._tag === "Close") return yield* stop(closed)
+		}
+	})
+
+	const machine = yield* Effect.forkScoped(loop)
+	yield* Effect.addFinalizer(() =>
+		Queue.offer(mailbox, { _tag: "Close" }).pipe(
+			Effect.andThen(Fiber.await(machine)),
+			Effect.andThen(FiberSet.clear(io))
+		)
+	)
+
+	return {
+		run: (request: Request) =>
+			Effect.suspend(() => {
+				if (stopped !== undefined) return Effect.fail(stopped)
+				const waiter = Deferred.makeUnsafe<Settled, DbError>()
+				const ticket = nextTicket
+				nextTicket += 1n
+				tickets.set(ticket, waiter)
+				Queue.offerUnsafe(mailbox, { _tag: "Request", ticket, request })
+				return Deferred.await(waiter)
+			})
+	}
+})
+
+const Driver = Object.freeze({ make, defaultOptions: defaultDriverOptions })
+
+export type { DriverOptions, MachinePort, Step }
+export { Driver }

package/src/database/fs.ts

@@ -0,0 +1,119 @@
+import { randomUUID } from "node:crypto"
+import * as fs from "node:fs/promises"
+import * as path from "node:path"
+import { Effect } from "effect"
+import { DbError } from "../errors.ts"
+import type { Body, Bucket, Created, Deleted, Fetched, Listed, ObjectStore, Reply, Target } from "./io.ts"
+
+function code(cause: unknown): string | undefined {
+	return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string"
+		? cause.code
+		: undefined
+}
+
+function attempt<A>(operation: string, run: () => Promise<A>): Effect.Effect<A, DbError> {
+	return Effect.tryPromise({
+		try: run,
+		catch: (cause) => new DbError({ operation, reason: { _tag: "Io", kind: code(cause) ?? "Unknown" } })
+	})
+}
+
+async function syncDirectory(directory: string): Promise<void> {
+	const handle = await fs.open(directory, "r")
+	try {
+		await handle.sync()
+	} finally {
+		await handle.close()
+	}
+}
+
+async function writeDurably(file: string, body: Body): Promise<void> {
+	if (body._tag === "File") await fs.copyFile(body.path, file, fs.constants.COPYFILE_EXCL)
+	const handle = await fs.open(file, body._tag === "File" ? "r+" : "wx")
+	try {
+		if (body._tag === "Bytes") await handle.writeFile(body.bytes)
+		await handle.sync()
+	} finally {
+		await handle.close()
+	}
+}
+
+/**
+ * A store in a local directory, one file per key under `root`. A create writes a temporary file,
+ * fsyncs it, hard-links it into place (the link fails if the key exists) and fsyncs the directory,
+ * so a created key is durable and never torn. The store clock is the local clock.
+ */
+function make(root: string): ObjectStore {
+	const file = (key: string) => path.join(root, ...key.split("/"))
+	const now = () => BigInt(Date.now())
+	return {
+		get: (_bucket: Bucket, key: string, target: Target) =>
+			attempt("FsStore.get", async (): Promise<Reply<Fetched>> => {
+				try {
+					if (target._tag === "Memory") {
+						const [bytes, stat] = await Promise.all([fs.readFile(file(key)), fs.stat(file(key), { bigint: true })])
+						return {
+							date: now(),
+							result: { _tag: "Body", bytes: new Uint8Array(bytes), lastModified: stat.mtimeMs }
+						}
+					}
+					const stat = await fs.stat(file(key), { bigint: true })
+					await fs.copyFile(file(key), target.path)
+					return { date: now(), result: { _tag: "Saved", lastModified: stat.mtimeMs } }
+				} catch (cause) {
+					if (code(cause) === "ENOENT") return { date: now(), result: { _tag: "Missing" } }
+					throw cause
+				}
+			}),
+		putIfAbsent: (_bucket: Bucket, key: string, body: Body) =>
+			attempt("FsStore.putIfAbsent", async (): Promise<Reply<Created>> => {
+				const target = file(key)
+				const directory = path.dirname(target)
+				await fs.mkdir(directory, { recursive: true })
+				const temporary = path.join(directory, `.tmp-${randomUUID()}`)
+				try {
+					await writeDurably(temporary, body)
+					try {
+						await fs.link(temporary, target)
+					} catch (cause) {
+						if (code(cause) === "EEXIST") return { date: now(), result: { _tag: "Occupied" } }
+						throw cause
+					}
+				} finally {
+					await fs.rm(temporary, { force: true })
+				}
+				await syncDirectory(directory)
+				return { date: now(), result: { _tag: "Created" } }
+			}),
+		list: (prefix: string, startAfter: string | null, maxKeys: number) =>
+			attempt("FsStore.list", async (): Promise<Reply<Listed>> => {
+				const directory = path.posix.dirname(`${prefix}_`)
+				let names: string[]
+				try {
+					names = await fs.readdir(path.join(root, ...directory.split("/")))
+				} catch (cause) {
+					if (code(cause) === "ENOENT") return { date: now(), result: { _tag: "Keys", keys: [] } }
+					throw cause
+				}
+				const keys = names
+					.filter((name) => !name.startsWith(".tmp-"))
+					.map((name) => (directory === "." ? name : `${directory}/${name}`))
+					.filter((key) => key.startsWith(prefix) && (startAfter === null || key > startAfter))
+					.sort()
+					.slice(0, maxKeys)
+				return { date: now(), result: { _tag: "Keys", keys } }
+			}),
+		delete: (key: string) =>
+			attempt("FsStore.delete", async (): Promise<Reply<Deleted>> => {
+				await fs.rm(file(key), { force: true })
+				await syncDirectory(path.dirname(file(key))).catch((cause) => {
+					if (code(cause) !== "ENOENT") throw cause
+				})
+				return { date: now(), result: { _tag: "Deleted" } }
+			})
+	}
+}
+
+const FsStore = Object.freeze({ make })
+
+export { FsStore }

package/src/database/generate.ts

@@ -0,0 +1,116 @@
+/**
+ * The migrations directory: one `NNNN_name/` per migration holding the schema it migrates to
+ * (`schema.json`, the engine's spec, and `schema.ts`, the same schema as SDK code) and its
+ * `migration.ts`; `index.ts` bundles them in order. A migration's hash covers its id and its
+ * `schema.json`, so editing either after it ran is caught by `check`.
+ */
+import { createHash } from "node:crypto"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { compiledOf } from "../compile.ts"
+import { AuthoringError } from "../errors.ts"
+import { lower } from "../lower.ts"
+import { addon } from "../native/addon.ts"
+import type { AnySchema } from "../schema.ts"
+import { schemaDescriptor } from "../schema.ts"
+
+const DIRECTORY = /^([0-9]{4})_([A-Za-z0-9_]+)$/
+
+/** The `schema.json` text of a schema: its lowered spec, formatted for review. */
+function specText(theory: AnySchema): string {
+	return `${JSON.stringify(lower(schemaDescriptor(theory)), null, "\t")}\n`
+}
+
+/** A migration's hash: sha256 over its id and its `schema.json` text. */
+function migrationHash(id: string, spec: string): string {
+	return createHash("sha256").update(`${id}\n${spec}`).digest("hex")
+}
+
+/** The migration directories under `root`, in order. */
+function migrationIds(root: string): string[] {
+	if (!fs.existsSync(root)) return []
+	return fs
+		.readdirSync(root, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory() && DIRECTORY.test(entry.name))
+		.map((entry) => entry.name)
+		.sort()
+}
+
+function indexText(ids: readonly string[]): string {
+	const imports = ids.map((id) => `import m${id.slice(0, 4)} from "./${id}/migration.ts"`)
+	const list = ids.map((id) => `m${id.slice(0, 4)}`).join(", ")
+	return `${imports.join("\n")}\n\nexport const migrations = [${list}] as const\n`
+}
+
+function migrationText(id: string, hash: string, previous: string | undefined): string {
+	const lines = ['import { Migration } from "@bjornpagen/bumbledb"']
+	if (previous !== undefined) lines.push(`import { schema as from } from "../${previous}/schema.ts"`)
+	lines.push('import { schema as to } from "./schema.ts"', "")
+	lines.push(
+		previous === undefined
+			? `export default Migration.make({ id: "${id}", hash: "${hash}", to })`
+			: `export default Migration.make({ id: "${id}", hash: "${hash}", from, to })`
+	)
+	return `${lines.join("\n")}\n`
+}
+
+type Generated = { readonly _tag: "Unchanged" } | { readonly _tag: "Created"; readonly id: string }
+
+/**
+ * Adds a migration to `schema` under `root` when it differs from the last migration's schema, and
+ * rewrites `index.ts`.
+ */
+function generate(root: string, theory: AnySchema, name: string): Generated {
+	if (!/^[A-Za-z0-9_]+$/.test(name))
+		throw new AuthoringError({ message: `migration name ${name}: letters, digits and _` })
+	const ids = migrationIds(root)
+	const spec = specText(theory)
+	const previous = ids.at(-1)
+	if (previous !== undefined && fs.readFileSync(path.join(root, previous, "schema.json"), "utf8") === spec) {
+		return { _tag: "Unchanged" }
+	}
+	const bindings = addon.schemaBindings(compiledOf(schemaDescriptor(theory)).handle)
+	if (bindings._tag === "Unrepresentable") {
+		throw new AuthoringError({ message: `schema ${theory.name}: ${bindings.coordinate}: ${bindings.reason}` })
+	}
+	const number = previous === undefined ? 1 : Number(previous.slice(0, 4)) + 1
+	const id = `${number.toString().padStart(4, "0")}_${name}`
+	const directory = path.join(root, id)
+	fs.mkdirSync(directory, { recursive: true })
+	fs.writeFileSync(path.join(directory, "schema.json"), spec)
+	fs.writeFileSync(path.join(directory, "schema.ts"), bindings.source)
+	fs.writeFileSync(path.join(directory, "migration.ts"), migrationText(id, migrationHash(id, spec), previous))
+	fs.writeFileSync(path.join(root, "index.ts"), indexText([...ids, id]))
+	return { _tag: "Created", id }
+}
+
+/** Everything `check` found wrong; empty when the directory is consistent with `schema`. */
+function check(
+	root: string,
+	theory: AnySchema,
+	bundled: readonly { readonly id: string; readonly hash: string }[]
+): string[] {
+	const problems: string[] = []
+	const ids = migrationIds(root)
+	if (ids.length === 0) return [`${root}: no migrations; run bumbledb generate`]
+	if (fs.readFileSync(path.join(root, "index.ts"), "utf8") !== indexText(ids)) {
+		problems.push(`${root}/index.ts does not list the migration directories in order; run bumbledb generate`)
+	}
+	ids.forEach((id, index) => {
+		const spec = fs.readFileSync(path.join(root, id, "schema.json"), "utf8")
+		const migration = bundled[index]
+		if (migration === undefined || migration.id !== id) {
+			problems.push(`${id}: not bundled at position ${index + 1}`)
+		} else if (migration.hash !== migrationHash(id, spec)) {
+			problems.push(`${id}: its hash does not match its schema.json; a migration is never edited after it runs`)
+		}
+	})
+	const last = ids.at(-1)
+	if (last !== undefined && fs.readFileSync(path.join(root, last, "schema.json"), "utf8") !== specText(theory)) {
+		problems.push(`the schema differs from ${last}; run bumbledb generate`)
+	}
+	return problems
+}
+
+export type { Generated }
+export { check, generate, migrationHash, migrationIds, specText }

package/src/database/hosted.ts

@@ -0,0 +1,102 @@
+/**
+ * The addon's hosted machine as a driver port. A hosted step is never cancelled: its output carries
+ * requests the machine then waits on, so every step runs to completion even when its caller is
+ * interrupted.
+ */
+import { Effect } from "effect"
+import type { DbError } from "../errors.ts"
+import type { ChangesRef, OperationRef } from "../native/addon.ts"
+import { addon } from "../native/addon.ts"
+import type {
+	CopyPair,
+	ExternalObject,
+	HeadOut,
+	HostedHandle,
+	IoOutcomeIn,
+	SettledOut,
+	StepOut
+} from "../native/binding.d.ts"
+import { call } from "../native/op.ts"
+import type { MachinePort, Step } from "./driver.ts"
+import type { IoResponse, IoResult } from "./io.ts"
+
+type HostedRef = ExternalObject<HostedHandle>
+
+/** One machine request. `request` ids are 32 hex digits; `revision` present is an exact-revision precondition. */
+type HostedRequest =
+	| { readonly _tag: "Open" }
+	| { readonly _tag: "Sync" }
+	| { readonly _tag: "Resolve"; readonly request: string }
+	| { readonly _tag: "Freeze"; readonly leaseMillis: bigint }
+	| {
+			readonly _tag: "Submit"
+			readonly request: string
+			readonly revision: bigint | null
+			readonly changes: ChangesRef
+	  }
+	| {
+			readonly _tag: "Migrate"
+			readonly step: number
+			readonly base: bigint
+			readonly copy: readonly CopyPair[]
+			readonly rows: ChangesRef
+	  }
+
+function outcomeIn(result: Exclude<IoResult, { readonly _tag: "Body" }>): IoOutcomeIn {
+	return result._tag === "Keys" ? { _tag: "Keys", keys: [...result.keys] } : result
+}
+
+/** A port over one hosted machine; `onHead` sees every head a step reports. */
+function hostedPort(hosted: HostedRef, onHead: (head: HeadOut) => void): MachinePort<HostedRequest, SettledOut> {
+	const step = (
+		operation: string,
+		start: (done: () => void) => OperationRef
+	): Effect.Effect<Step<SettledOut>, DbError> =>
+		call(operation, start, addon.hostedStepTake).pipe(
+			Effect.tap((out: StepOut) =>
+				Effect.sync(() => {
+					if (out.head !== undefined) onHead(out.head)
+				})
+			),
+			Effect.uninterruptible
+		)
+	return {
+		request: (ticket, request) => {
+			switch (request._tag) {
+				case "Open":
+				case "Sync":
+					return step(`Database.${request._tag}`, (done) =>
+						addon.hostedStep(hosted, { _tag: request._tag, ticket }, done)
+					)
+				case "Resolve":
+					return step("Database.resolve", (done) =>
+						addon.hostedStep(hosted, { _tag: "Resolve", ticket, request: request.request }, done)
+					)
+				case "Freeze":
+					return step("Database.freeze", (done) =>
+						addon.hostedStep(hosted, { _tag: "Freeze", ticket, leaseMillis: request.leaseMillis }, done)
+					)
+				case "Submit":
+					return step("Database.submit", (done) =>
+						addon.hostedSubmit(hosted, ticket, request.request, request.revision, request.changes, done)
+					)
+				case "Migrate":
+					return step("Database.migrate", (done) =>
+						addon.hostedMigrate(hosted, ticket, request.step, request.base, [...request.copy], request.rows, done)
+					)
+			}
+		},
+		respond: (response: IoResponse) => {
+			const { id, date, result } = response
+			return result._tag === "Body"
+				? step("Database.respond", (done) =>
+						addon.hostedRespondBody(hosted, id, date, result.lastModified, result.bytes, done)
+					)
+				: step("Database.respond", (done) => addon.hostedRespond(hosted, id, date, outcomeIn(result), done))
+		},
+		close: step("Database.close", (done) => addon.hostedStep(hosted, { _tag: "Close" }, done))
+	}
+}
+
+export type { HostedRef, HostedRequest }
+export { hostedPort }

package/src/database/io.ts

@@ -0,0 +1,134 @@
+/**
+ * The object-store side of the hosted log. The log machine emits `IoRequest`s as data; this module
+ * runs them against an `ObjectStore` and turns every outcome into an `IoResponse`. Reads are
+ * idempotent and retried here; a create-only PUT is never retried here, because the machine
+ * resolves an ambiguous PUT by reading the key back.
+ */
+import type { Duration } from "effect"
+import { Effect, Schedule } from "effect"
+import { DbError } from "../errors.ts"
+import type { BucketOut, IoRequestOut } from "../native/binding.d.ts"
+
+/** `Log` is the commit log (`log/`, an S3 Express directory bucket); `Checkpoints` holds `ckpt/` and `mig/`. */
+type Bucket = BucketOut
+
+/** One request from the machine. `key` is relative to the database prefix. */
+type IoRequest = IoRequestOut
+
+/** Unix milliseconds on the store's clock. */
+type Millis = bigint
+
+/** Where a GET delivers the object: returned in memory, or written to a local file. */
+type Target = { readonly _tag: "Memory" } | { readonly _tag: "File"; readonly path: string }
+
+/** What a create-only PUT uploads: bytes in memory, or a local file. */
+type Body = { readonly _tag: "Bytes"; readonly bytes: Uint8Array } | { readonly _tag: "File"; readonly path: string }
+
+type Fetched =
+	| { readonly _tag: "Body"; readonly bytes: Uint8Array; readonly lastModified: Millis }
+	| { readonly _tag: "Saved"; readonly lastModified: Millis }
+	| { readonly _tag: "Missing" }
+
+/** `Occupied`: the key exists, or, for a log object, another conditional write to it was in progress. */
+type Created = { readonly _tag: "Created" } | { readonly _tag: "Occupied" }
+
+type Listed = { readonly _tag: "Keys"; readonly keys: readonly string[] }
+
+type Deleted = { readonly _tag: "Deleted" }
+
+/** `Failed` covers everything a store could not answer definitively: 5xx, timeouts, transport. */
+type IoResult = Fetched | Created | Listed | Deleted | { readonly _tag: "Failed" }
+
+interface IoResponse {
+	readonly id: bigint
+	/** The store's `Date` header, when it sent one. */
+	readonly date: Millis | null
+	readonly result: IoResult
+}
+
+/** A store answer plus the store's clock reading. */
+interface Reply<R> {
+	readonly date: Millis | null
+	readonly result: R
+}
+
+/**
+ * The four verbs the log needs. Keys arrive relative; a store owns its own prefix. LIST and DELETE
+ * exist only for `Checkpoints`: LIST order on an Express bucket is not lexicographic, and a `log/`
+ * key must never disappear.
+ */
+interface ObjectStore {
+	readonly get: (bucket: Bucket, key: string, target: Target) => Effect.Effect<Reply<Fetched>, DbError>
+	readonly putIfAbsent: (bucket: Bucket, key: string, body: Body) => Effect.Effect<Reply<Created>, DbError>
+	/** Checkpoint keys under `prefix` after `startAfter`, in lexicographic order. */
+	readonly list: (prefix: string, startAfter: string | null, maxKeys: number) => Effect.Effect<Reply<Listed>, DbError>
+	/** Deletes one checkpoint key; deleting a missing key succeeds. */
+	readonly delete: (key: string) => Effect.Effect<Reply<Deleted>, DbError>
+}
+
+interface ExecutorOptions {
+	/** Bound on one store call; a call that exceeds it counts as `Failed` (or is retried, for a read). */
+	readonly timeout: Duration.Input
+	/** Retry policy for GET, LIST and DELETE. */
+	readonly readRetry: Schedule.Schedule<unknown, unknown>
+}
+
+const defaultExecutorOptions: ExecutorOptions = {
+	timeout: "10 seconds",
+	readRetry: Schedule.exponential("20 millis").pipe(Schedule.jittered, Schedule.upTo({ times: 4 }))
+}
+
+function refused(request: IoRequest): Effect.Effect<never, DbError> {
+	return Effect.fail(new DbError({ operation: `ObjectStore.${request.op._tag}`, reason: { _tag: "InvalidArgument" } }))
+}
+
+function dispatch(store: ObjectStore, request: IoRequest): Effect.Effect<Reply<IoResult>, DbError> {
+	const { bucket, key, op } = request
+	switch (op._tag) {
+		case "GetMemory":
+			return store.get(bucket, key, { _tag: "Memory" })
+		case "GetFile":
+			return store.get(bucket, key, { _tag: "File", path: op.path })
+		case "PutBytes":
+			return store.putIfAbsent(bucket, key, { _tag: "Bytes", bytes: op.bytes })
+		case "PutFile":
+			return store.putIfAbsent(bucket, key, { _tag: "File", path: op.path })
+		case "List":
+			return bucket === "Checkpoints" ? store.list(key, op.startAfter ?? null, op.maxKeys) : refused(request)
+		case "Delete":
+			return bucket === "Checkpoints" ? store.delete(key) : refused(request)
+	}
+}
+
+/** Runs one request to an `IoResponse`; it never fails. */
+function execute(
+	store: ObjectStore,
+	request: IoRequest,
+	options: ExecutorOptions = defaultExecutorOptions
+): Effect.Effect<IoResponse> {
+	const once = Effect.timeout(dispatch(store, request), options.timeout)
+	const write = request.op._tag === "PutBytes" || request.op._tag === "PutFile"
+	const attempts = write ? once : Effect.retry(once, options.readRetry)
+	return attempts.pipe(
+		Effect.map((reply): IoResponse => ({ id: request.id, date: reply.date, result: reply.result })),
+		Effect.catch(() => Effect.succeed<IoResponse>({ id: request.id, date: null, result: { _tag: "Failed" } }))
+	)
+}
+
+export type {
+	Body,
+	Bucket,
+	Created,
+	Deleted,
+	ExecutorOptions,
+	Fetched,
+	IoRequest,
+	IoResponse,
+	IoResult,
+	Listed,
+	Millis,
+	ObjectStore,
+	Reply,
+	Target
+}
+export { defaultExecutorOptions, execute }