@ariestools/aries-dapp-core 0.1.8 → 0.1.9

package/README.md

@@ -152,12 +152,85 @@ published head).
 ## Local daemon (dev only)
 
 The composed bin (`dist/bin/dappServer.mjs`) starts the storage server and a
-`noopReducer` actor. `aries dapp up` spawns it.
+DappActor. `aries dapp up` spawns it.
 
-Env: `DAPP_PORT` (8801), `HOST` (127.0.0.1), `DAPP_BACKING` (`memory`),
-`DAPP_PUBLIC_HOST`, `DAPP_TLS_CERT`, `DAPP_TLS_KEY`, `DAPP_REDUCE_INTERVAL_MS`
-(5000). Under `--ssl auto` the daemon exports the local CA via
-`NODE_EXTRA_CA_CERTS`.
+### CLI
+
+```sh
+# Empty spine (noop reducer)
+aries dapp up
+
+# Real project reducer (ESM .mjs or package export — TypeScript not supported)
+aries dapp up --reducer ./dist/indexer.mjs
+aries dapp up --reducer ./dist/indexer.mjs --reducer-export myIndex
+aries dapp up --reducer @myorg/my-dapp/indexer
+
+# Persist buckets across restarts
+aries dapp up --backing disk --data-dir ~/.aries/dapp/data
+```
+
+Example reducer shipped with this package:
+
+```sh
+aries dapp up --reducer ./node_modules/@ariestools/aries-dapp-core/examples/countFactsReducer.mjs
+# monorepo:
+aries dapp up --reducer ./packages/dapp-core/examples/countFactsReducer.mjs
+```
+
+### Reducer module contract
+
+The module must export a `DappReducer`:
+
+- **default export**, or
+- named export `reducer`, or
+- any name via `--reducer-export` / `DAPP_REDUCER_EXPORT`
+
+```js
+// dist/indexer.mjs
+export default {
+  name: 'my-index',
+  version: '1',
+  async reduce({ data, state, index, signal, logger }) {
+    // read data, publishGeneration / publishIncremental, return progress
+  },
+}
+```
+
+Local publication should use `safety: { mode: 'unfenced' }` (or honor
+`DAPP_PUBLICATION_SAFETY`, which the daemon sets to `unfenced` by default).
+s3rver does not support reliable head CAS.
+
+### Env (daemon)
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `DAPP_PORT` | `8801` | |
+| `HOST` | `127.0.0.1` | |
+| `DAPP_BACKING` | `memory` | `memory` \| `disk` |
+| `DAPP_DATA_DIR` | `~/.aries/dapp/data` | disk root |
+| `DAPP_REDUCER` | _(noop)_ | path to `.mjs`/`.js` or package export |
+| `DAPP_REDUCER_EXPORT` | default / `reducer` | named export |
+| `DAPP_REDUCE_INTERVAL_MS` | `5000` | |
+| `DAPP_FIRST_RUN_DELAY_MS` | `0` | |
+| `DAPP_PUBLICATION_SAFETY` | `unfenced` | set by daemon for project reducers |
+| `DAPP_PUBLIC_HOST` / `DAPP_TLS_*` | | `--ssl auto` |
+
+Under `--ssl auto` the daemon exports the local CA via `NODE_EXTRA_CA_CERTS`.
+
+## Production entrypoint (not the CLI bin)
+
+Do **not** run `aries-dapp-server` or `aries dapp up` in production. Write a
+project-owned process that:
+
+1. Builds an `S3Client` for R2/S3 (credentials from env/IAM — never logged)
+2. Calls `createDappLocator({ client, bindings, ownClient: true })`
+3. Implements a `DappReducer` (import statically — no dynamic CLI load required)
+4. Calls `bootDappActors` with `safety: { mode: 'conditional-head' }` inside
+   `publishGeneration` / `publishIncremental`
+5. Listens for SIGTERM and stops actors + `locator.destroy()`
+
+See `examples/productionComposition.ts` and the composition section above.
+There is no inbound public listener; clients read head/status/objects from CDN.
 
 ## Least-privilege IAM / R2 notes
 

package/dist/bin/dappServer.mjs

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
 import { DAPP_BACKINGS, DAPP_BUCKETS, isDappBackingKind, resolveBacking, startDappServer } from "@ariestools/aries-dapp-serve";
 import { AbstractCreatable, ConsoleLogger, IdLogger, assertEx, creatable } from "@ariestools/sdk";
 import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { pathToFileURL } from "node:url";
 //#region src/actor/AbstractActor.ts
 function createDeferred$1() {
 	let resolve;
@@ -837,16 +841,62 @@ const noopReducer = {
 	async reduce() {}
 };
 //#endregion
+//#region src/bin/loadReducer.ts
+const require = createRequire(import.meta.url);
+function isPathSpec(spec) {
+	return spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("file:") || path.isAbsolute(spec) || spec.endsWith(".mjs") || spec.endsWith(".js") || spec.endsWith(".cjs");
+}
+function resolveFileUrl(spec) {
+	if (spec.startsWith("file:")) return spec;
+	const absolute = path.isAbsolute(spec) ? spec : path.resolve(process.cwd(), spec);
+	if (!existsSync(absolute)) throw new Error(`Reducer module not found: ${absolute}`);
+	return pathToFileURL(absolute).href;
+}
+function resolvePackageUrl(spec) {
+	try {
+		return pathToFileURL(require.resolve(spec, { paths: [process.cwd()] })).href;
+	} catch {
+		throw new Error(`Could not resolve reducer package "${spec}" from ${process.cwd()}. Pass a path to a .mjs file or an installed package export.`);
+	}
+}
+function pickReducer(mod, exportName) {
+	if (exportName !== void 0 && exportName.length > 0) {
+		if (!(exportName in mod)) throw new Error(`Reducer module has no export named "${exportName}"`);
+		return mod[exportName];
+	}
+	if (mod.default !== void 0) return mod.default;
+	if (mod.reducer !== void 0) return mod.reducer;
+	throw new Error("Reducer module must default-export a DappReducer, or export `reducer`, or set DAPP_REDUCER_EXPORT / --reducer-export to a named export");
+}
+function assertReducer(value, label) {
+	if (value === null || typeof value !== "object") throw new TypeError(`${label} is not an object`);
+	const candidate = value;
+	if (typeof candidate.name !== "string" || candidate.name.length === 0) throw new TypeError(`${label} must have a non-empty string "name"`);
+	if (typeof candidate.reduce !== "function") throw new TypeError(`${label} must have a "reduce" function`);
+	return candidate;
+}
+/**
+* Dynamically load a project-owned reducer for the local dapp daemon.
+* Supports filesystem `.mjs`/`.js` paths and package export strings.
+* TypeScript sources are not supported — build to ESM first.
+*/
+async function loadReducer(options) {
+	return assertReducer(pickReducer(await (isPathSpec(options.spec) ? import(resolveFileUrl(options.spec)) : import(resolvePackageUrl(options.spec))), options.exportName), `Reducer from ${options.spec}`);
+}
+//#endregion
 //#region src/bin/dappServer.ts
 /**
 * **Local development only.** Composed dapp daemon: boots the embedded
 * S3-compatible storage server (from `@ariestools/aries-dapp-serve`) and, in
-* the same process, a shared process-wide locator plus a `noopReducer`
-* DappActor. Spawned by `aries dapp up`.
+* the same process, a shared process-wide locator plus DappActor(s).
+* Spawned by `aries dapp up`.
 *
-* Production indexers must not use this binary. Compose `dapp-core` from a
-* project-owned entrypoint with real store bindings, an injected S3/R2 client,
-* and a real reducer — see the package README.
+* Optional `DAPP_REDUCER` loads a project-owned ESM reducer (`.mjs` path or
+* package export). Without it, `noopReducer` runs so the spine still works.
+*
+* Production indexers should **not** use this binary. Compose `dapp-core` from
+* a project-owned entrypoint with real R2/S3 bindings and a real reducer —
+* see the package README and `examples/`.
 */
 const PORT = Number(process.env.DAPP_PORT ?? 8801);
 const HOST = process.env.HOST ?? "127.0.0.1";
@@ -855,10 +905,22 @@ const PUBLIC_HOST = process.env.DAPP_PUBLIC_HOST;
 const TLS_CERT_PATH = process.env.DAPP_TLS_CERT;
 const TLS_KEY_PATH = process.env.DAPP_TLS_KEY;
 const REDUCE_INTERVAL_MS = Number(process.env.DAPP_REDUCE_INTERVAL_MS ?? 5e3);
+const FIRST_RUN_DELAY_MS = Number(process.env.DAPP_FIRST_RUN_DELAY_MS ?? 0);
+const REDUCER_SPEC = process.env.DAPP_REDUCER;
+const REDUCER_EXPORT = process.env.DAPP_REDUCER_EXPORT;
+const DATA_DIR = process.env.DAPP_DATA_DIR ?? path.join(process.env.ARIES_HOME ?? path.join(homedir(), ".aries"), "dapp", "data");
+async function resolveDaemonReducer() {
+	if (REDUCER_SPEC === void 0 || REDUCER_SPEC.length === 0) return noopReducer;
+	return await loadReducer({
+		spec: REDUCER_SPEC,
+		...REDUCER_EXPORT !== void 0 && REDUCER_EXPORT.length > 0 && { exportName: REDUCER_EXPORT }
+	});
+}
 async function main() {
 	if (!isDappBackingKind(BACKING)) throw new Error(`Unsupported DAPP_BACKING '${BACKING}' (supported: ${DAPP_BACKINGS.join(", ")})`);
 	if (TLS_CERT_PATH === void 0 !== (TLS_KEY_PATH === void 0)) throw new Error("DAPP_TLS_CERT and DAPP_TLS_KEY must be provided together");
-	const backing = resolveBacking(BACKING);
+	const reducer = await resolveDaemonReducer();
+	const backing = resolveBacking(BACKING, { ...BACKING === "disk" && { directory: DATA_DIR } });
 	const server = await startDappServer({
 		backing,
 		host: HOST,
@@ -872,16 +934,21 @@ async function main() {
 	const logger = new ConsoleLogger();
 	const locator = createDappLocator({
 		endpoint: server.baseUrl,
-		logger
+		logger,
+		readOnlyData: false
 	});
+	process.env.DAPP_PUBLICATION_SAFETY ??= "unfenced";
+	process.env.DAPP_ENDPOINT ??= server.baseUrl;
 	const actors = await bootDappActors(locator, [{
 		name: "DappActor",
-		reducer: noopReducer,
+		reducer,
 		reduceIntervalMs: REDUCE_INTERVAL_MS,
-		firstRunDelayMs: 0,
-		publishStatus: false
+		firstRunDelayMs: FIRST_RUN_DELAY_MS,
+		publishStatus: reducer.name !== "noop"
 	}]);
-	console.log(`[dev-only] dapp server listening at ${server.baseUrl}\n` + DAPP_BUCKETS.map((bucket) => `  /${bucket.padEnd(5)} ${server.baseUrl}/${bucket}`).join("\n") + `\nbacking: ${backing.description} — ${backing.directory}\nactors: ${actors.length} (reducer '${noopReducer.name}', every ${REDUCE_INTERVAL_MS}ms)`);
+	const versionSuffix = reducer.version === void 0 ? "" : `@${reducer.version}`;
+	const reducerLine = REDUCER_SPEC === void 0 ? "\nreducer: noop (pass DAPP_REDUCER / --reducer for real logic)" : `\nreducer: ${REDUCER_SPEC}`;
+	console.log(`[dev-only] dapp server listening at ${server.baseUrl}\n` + DAPP_BUCKETS.map((bucket) => `  /${bucket.padEnd(5)} ${server.baseUrl}/${bucket}`).join("\n") + `\nbacking: ${backing.description}\nactors: ${actors.length} (reducer '${reducer.name}'${versionSuffix}, every ${REDUCE_INTERVAL_MS}ms)` + reducerLine);
 	const shutdown = async () => {
 		for (const actor of actors) await actor.stop();
 		locator.destroy();

package/dist/node/bin/dappServer.d.ts

@@ -2,12 +2,15 @@
 /**
  * **Local development only.** Composed dapp daemon: boots the embedded
  * S3-compatible storage server (from `@ariestools/aries-dapp-serve`) and, in
- * the same process, a shared process-wide locator plus a `noopReducer`
- * DappActor. Spawned by `aries dapp up`.
+ * the same process, a shared process-wide locator plus DappActor(s).
+ * Spawned by `aries dapp up`.
  *
- * Production indexers must not use this binary. Compose `dapp-core` from a
- * project-owned entrypoint with real store bindings, an injected S3/R2 client,
- * and a real reducer — see the package README.
+ * Optional `DAPP_REDUCER` loads a project-owned ESM reducer (`.mjs` path or
+ * package export). Without it, `noopReducer` runs so the spine still works.
+ *
+ * Production indexers should **not** use this binary. Compose `dapp-core` from
+ * a project-owned entrypoint with real R2/S3 bindings and a real reducer —
+ * see the package README and `examples/`.
  */
 export {};
 //# sourceMappingURL=dappServer.d.ts.map

package/dist/node/bin/dappServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dappServer.d.ts","sourceRoot":"","sources":["../../../src/bin/dappServer.ts"],"names":[],"mappings":";AAEA;;;;;;;;;GASG"}
+{"version":3,"file":"dappServer.d.ts","sourceRoot":"","sources":["../../../src/bin/dappServer.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG"}

package/dist/node/bin/loadReducer.d.ts

@@ -0,0 +1,17 @@
+import type { DappReducer } from '../reducer/DappReducer.ts';
+export interface LoadReducerOptions {
+    /**
+     * Named export to prefer when the module has no default export.
+     * Defaults to trying `reducer`, then `default`.
+     */
+    exportName?: string;
+    /** Absolute or relative path to a `.mjs` file, or a resolvable package export. */
+    spec: string;
+}
+/**
+ * Dynamically load a project-owned reducer for the local dapp daemon.
+ * Supports filesystem `.mjs`/`.js` paths and package export strings.
+ * TypeScript sources are not supported — build to ESM first.
+ */
+export declare function loadReducer(options: LoadReducerOptions): Promise<DappReducer>;
+//# sourceMappingURL=loadReducer.d.ts.map

package/dist/node/bin/loadReducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadReducer.d.ts","sourceRoot":"","sources":["../../../src/bin/loadReducer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAI5D,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAA;CACb;AA6DD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAOnF"}

package/dist/node/examples/productionComposition.d.ts

@@ -1,10 +1,14 @@
 /**
- * Project-owned production composition example (documentation / type-check only).
+ * Project-owned **production** composition example (documentation / type-check only).
  *
- * This is **not** a runnable daemon and is **not** imported by the published bin.
- * Copy the pattern into your application entrypoint. dapp-core stays
- * application-neutral: you supply the reducer, store bindings, credentials, and
- * any XL1/gateway readers. There is no inbound public listener and no
+ * This is **not** the local `aries dapp up` / `aries-dapp-server` path.
+ * For local dev with a pluggable reducer, use:
+ *
+ *   aries dapp up --reducer ./dist/indexer.mjs
+ *
+ * For production: copy this pattern into your application entrypoint. dapp-core
+ * stays application-neutral: you supply the reducer, store bindings, credentials,
+ * and any XL1/gateway readers. There is no inbound public listener and no
  * application authority/signing seed stored in dapp-core.
  *
  * ```ts

package/dist/node/examples/productionComposition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"productionComposition.d.ts","sourceRoot":"","sources":["../../../src/examples/productionComposition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+GG;AAEH,OAAO,EAAE,CAAA"}
+{"version":3,"file":"productionComposition.d.ts","sourceRoot":"","sources":["../../../src/examples/productionComposition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG;AAEH,OAAO,EAAE,CAAA"}

package/examples/countFactsReducer.mjs

@@ -0,0 +1,96 @@
+/**
+ * Example local-dev reducer for `aries dapp up --reducer`.
+ *
+ * Counts JSON objects under data/facts/, then publishes a coherent generation
+ * with the local unfenced safety mode (s3rver does not support head CAS).
+ *
+ * Usage (from a built monorepo):
+ *
+ *   pnpm xy build @ariestools/aries-dapp-core
+ *   aries dapp up --reducer ./packages/dapp-core/examples/countFactsReducer.mjs
+ *
+ * Seed data (path-style, any credentials):
+ *
+ *   export S3_ENDPOINT=http://127.0.0.1:8801
+ *   # put facts into the data bucket, e.g. with aws cli --endpoint-url
+ *
+ * Production: do **not** use this daemon. Compose dapp-core in your own
+ * process with R2 bindings and safety: { mode: 'conditional-head' }.
+ */
+
+// Package-name import is intentional so this file is a drop-in template for
+// app repos; monorepo eslint forbids absolute self-imports, so disable here.
+// eslint-disable-next-line workspaces/no-absolute-imports -- example template
+import {
+  publishGeneration,
+  readPublishedHead,
+} from '@ariestools/aries-dapp-core'
+
+/** @type {import('@ariestools/aries-dapp-core').DappReducer} */
+export const reducer = {
+  name: 'count-facts',
+  version: '1',
+  async reduce({
+    data, state, index, signal, logger,
+  }) {
+    const keys = (await data.list('facts/')).sort()
+    const facts = []
+    for (const key of keys) {
+      const body = await data.get(key)
+      if (body === undefined) continue
+      facts.push(JSON.parse(new TextDecoder().decode(body)))
+    }
+
+    const prior = await readPublishedHead(state)
+    const safetyMode = process.env.DAPP_PUBLICATION_SAFETY === 'conditional-head'
+      ? 'conditional-head'
+      : 'unfenced'
+
+    const published = await publishGeneration({
+      state,
+      index,
+      safety: { mode: safetyMode },
+      assertSafety: safetyMode === 'conditional-head',
+      ...(prior?.headEtag !== undefined && { expectedHeadEtag: prior.headEtag }),
+      ...(prior?.head.generation !== undefined
+        && { previousGeneration: prior.head.generation }),
+      revision: (prior?.head.revision ?? 0) + 1,
+      reducer: { name: 'count-facts', version: '1' },
+      schemaVersion: '1',
+      source: {
+        cursor: String(facts.length),
+        completedPosition: String(facts.length),
+        observedHead: String(facts.length),
+      },
+      stateObjects: [{
+        key: 'view.json',
+        body: JSON.stringify({ count: facts.length, facts }),
+        contentType: 'application/json',
+      }],
+      indexObjects: [{
+        key: 'by-id.json',
+        body: JSON.stringify(Object.fromEntries(
+          facts.map(f => [String(f.id ?? ''), f]),
+        )),
+        contentType: 'application/json',
+      }],
+      signal,
+    })
+
+    if (!published.ok) {
+      logger.warn(`publish conflict: ${published.conflict.kind} ${published.conflict.message}`)
+      return
+    }
+
+    logger.info(`published generation ${published.generation} (count=${facts.length})`)
+    return {
+      cursor: String(facts.length),
+      lastCompletedPosition: String(facts.length),
+      observedSourceHead: String(facts.length),
+      generation: published.generation,
+      generationRoot: published.manifestKey,
+    }
+  },
+}
+
+export default reducer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariestools/aries-dapp-core",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Aries dapp backend core: the DappActor (forked xl1 actor pattern), process-wide provider locator, pluggable reducer, and the composed daemon that runs the storage server plus actors",
   "keywords": [
     "ariestools",
@@ -35,17 +35,18 @@
   },
   "files": [
     "dist",
+    "examples",
     "README.md"
   ],
   "dependencies": {
-    "@ariestools/sdk": "~8.1.1",
+    "@ariestools/sdk": "~8.1.2",
     "@aws-sdk/client-s3": "~3.1090.0",
     "tslib": "~2.8.1",
-    "@ariestools/aries-dapp-serve": "~0.1.8"
+    "@ariestools/aries-dapp-serve": "~0.1.9"
   },
   "devDependencies": {
-    "@ariestools/toolchain": "~8.7.16",
-    "@ariestools/tsconfig": "~8.7.16",
+    "@ariestools/toolchain": "~8.7.20",
+    "@ariestools/tsconfig": "~8.7.20",
     "@opentelemetry/api": "~1.9.1",
     "@types/node": "~26.1.1",
     "rolldown": "~1.2.0",