@ariestools/aries-dapp-serve 0.1.7

package/README.md

@@ -0,0 +1,31 @@
+# @ariestools/aries-dapp-serve
+
+> **Dev only.** This package is a local development fixture — it accepts any
+> S3 credentials, carries no auth or metrics, and only ships an ephemeral
+> in-memory backing. It is not meant for production at this time; production
+> dapp backends are published to real object storage (S3/R2) behind the
+> standard sub-domain layout.
+
+Serves a dapp backend's layout from a single origin using subfolders
+(`/state`, `/data`, `/index`) — the S3-compatible storage half of the
+`aries dapp` local backend. The subfolders are S3 buckets on an embedded
+S3-compatible server ([s3rver](https://www.npmjs.com/package/s3rver)), so any
+S3 client writes into them unchanged while readers (browser dapps, `curl`)
+fetch the same layout paths over plain HTTP or optional TLS.
+
+The three buckets:
+
+- **`data`** — immutable, append-only facts (the source of truth).
+- **`state`** — mutable current derived view, rebuilt on an interval by the
+  `DappActor`.
+- **`index`** — query-optimized derived views, rebuilt on an interval by the
+  `DappActor`.
+
+This package is the storage layer only. The `DappActor` that derives `state`
+and `index` from `data`, and the composed daemon that runs both the server
+and the actor, live in
+[`@ariestools/aries-dapp-core`](../dapp-core). `aries dapp up` spawns that
+composed daemon.
+
+Backings (`DappBackingKind`): `memory` (ephemeral temp directory, wiped on
+shutdown). `disk` and `s3` are planned.

package/dist/node/DappBacking.d.ts

@@ -0,0 +1,21 @@
+export declare const DAPP_BACKINGS: readonly ["memory"];
+export type DappBackingKind = typeof DAPP_BACKINGS[number];
+export declare function isDappBackingKind(value: string): value is DappBackingKind;
+/**
+ * Where the served dapp layout's objects live. v1 ships only `memory` (an
+ * ephemeral temp directory wiped on shutdown); a `disk` kind (caller-owned
+ * directory, no-op cleanup) is the natural next addition. An `s3` kind will
+ * proxy a remote bucket instead of running a local store, so it will lift
+ * this seam up to the server level rather than fit this interface.
+ */
+export interface DappBacking {
+    /** Human-readable label for banners and status output. */
+    readonly description: string;
+    /** Directory the S3-compatible server persists bucket objects under. Only valid after prepare(). */
+    readonly directory: string;
+    cleanup(): Promise<void>;
+    prepare(): Promise<void>;
+}
+export declare function createMemoryBacking(): DappBacking;
+export declare function resolveBacking(kind: DappBackingKind): DappBacking;
+//# sourceMappingURL=DappBacking.d.ts.map

package/dist/node/DappBacking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DappBacking.d.ts","sourceRoot":"","sources":["../../src/DappBacking.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,aAAa,qBAAsB,CAAA;AAChD,MAAM,MAAM,eAAe,GAAG,OAAO,aAAa,CAAC,MAAM,CAAC,CAAA;AAE1D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,eAAe,CAEzE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,oGAAoG;IACpG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,wBAAgB,mBAAmB,IAAI,WAAW,CAgBjD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAMjE"}

package/dist/node/index.d.ts

@@ -0,0 +1,5 @@
+export type { DappBacking, DappBackingKind } from './DappBacking.ts';
+export { createMemoryBacking, DAPP_BACKINGS, isDappBackingKind, resolveBacking, } from './DappBacking.ts';
+export type { DappBucket, DappServerOptions, RunningDappServer, } from './startDappServer.ts';
+export { DAPP_BUCKETS, startDappServer } from './startDappServer.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACpE,OAAO,EACL,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,GACtE,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,UAAU,EAAE,iBAAiB,EAAE,iBAAiB,GACjD,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/node/index.mjs

@@ -0,0 +1,85 @@
+// src/DappBacking.ts
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+var DAPP_BACKINGS = ["memory"];
+function isDappBackingKind(value) {
+  return DAPP_BACKINGS.includes(value);
+}
+function createMemoryBacking() {
+  let dir;
+  return {
+    description: "memory (ephemeral temp directory)",
+    get directory() {
+      if (dir === void 0) throw new Error("Memory backing not prepared");
+      return dir;
+    },
+    async prepare() {
+      dir ??= await mkdtemp(path.join(tmpdir(), "aries-dapp-"));
+    },
+    async cleanup() {
+      if (dir !== void 0) await rm(dir, { recursive: true, force: true });
+      dir = void 0;
+    }
+  };
+}
+function resolveBacking(kind) {
+  switch (kind) {
+    case "memory": {
+      return createMemoryBacking();
+    }
+  }
+}
+
+// src/startDappServer.ts
+import S3rver from "s3rver";
+var DAPP_BUCKETS = ["state", "data", "index"];
+var DEFAULT_HOST = "127.0.0.1";
+var DEFAULT_PORT = 8801;
+var CORS_ALLOW_READS = `<CORSConfiguration>
+  <CORSRule>
+    <AllowedOrigin>*</AllowedOrigin>
+    <AllowedMethod>GET</AllowedMethod>
+    <AllowedMethod>HEAD</AllowedMethod>
+    <AllowedHeader>*</AllowedHeader>
+  </CORSRule>
+</CORSConfiguration>`;
+async function startDappServer(options) {
+  const host = options.host ?? DEFAULT_HOST;
+  const publicHost = options.publicHost ?? host;
+  await options.backing.prepare();
+  const server = new S3rver({
+    address: host,
+    allowMismatchedSignatures: true,
+    cert: options.tls?.cert,
+    configureBuckets: DAPP_BUCKETS.map((name) => ({ name, configs: [CORS_ALLOW_READS] })),
+    directory: options.backing.directory,
+    key: options.tls?.key,
+    port: options.port ?? DEFAULT_PORT,
+    silent: options.silent ?? false,
+    vhostBuckets: false
+  });
+  try {
+    const { port } = await server.run();
+    return {
+      baseUrl: `${options.tls === void 0 ? "http" : "https"}://${publicHost}:${port}`,
+      port,
+      close: async () => {
+        await server.close();
+        await options.backing.cleanup();
+      }
+    };
+  } catch (error) {
+    await options.backing.cleanup();
+    throw error;
+  }
+}
+export {
+  DAPP_BACKINGS,
+  DAPP_BUCKETS,
+  createMemoryBacking,
+  isDappBackingKind,
+  resolveBacking,
+  startDappServer
+};
+//# sourceMappingURL=index.mjs.map

package/dist/node/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/DappBacking.ts", "../../src/startDappServer.ts"],
+  "sourcesContent": ["import { mkdtemp, rm } from 'node:fs/promises'\nimport { tmpdir } from 'node:os'\nimport path from 'node:path'\n\nexport const DAPP_BACKINGS = ['memory'] as const\nexport type DappBackingKind = typeof DAPP_BACKINGS[number]\n\nexport function isDappBackingKind(value: string): value is DappBackingKind {\n  return (DAPP_BACKINGS as readonly string[]).includes(value)\n}\n\n/**\n * Where the served dapp layout's objects live. v1 ships only `memory` (an\n * ephemeral temp directory wiped on shutdown); a `disk` kind (caller-owned\n * directory, no-op cleanup) is the natural next addition. An `s3` kind will\n * proxy a remote bucket instead of running a local store, so it will lift\n * this seam up to the server level rather than fit this interface.\n */\nexport interface DappBacking {\n  /** Human-readable label for banners and status output. */\n  readonly description: string\n  /** Directory the S3-compatible server persists bucket objects under. Only valid after prepare(). */\n  readonly directory: string\n  cleanup(): Promise<void>\n  prepare(): Promise<void>\n}\n\nexport function createMemoryBacking(): DappBacking {\n  let dir: string | undefined\n  return {\n    description: 'memory (ephemeral temp directory)',\n    get directory(): string {\n      if (dir === undefined) throw new Error('Memory backing not prepared')\n      return dir\n    },\n    async prepare(): Promise<void> {\n      dir ??= await mkdtemp(path.join(tmpdir(), 'aries-dapp-'))\n    },\n    async cleanup(): Promise<void> {\n      if (dir !== undefined) await rm(dir, { recursive: true, force: true })\n      dir = undefined\n    },\n  }\n}\n\nexport function resolveBacking(kind: DappBackingKind): DappBacking {\n  switch (kind) {\n    case 'memory': {\n      return createMemoryBacking()\n    }\n  }\n}\n", "import S3rver from 's3rver'\n\nimport type { DappBacking } from './DappBacking.ts'\n\n/**\n * The bucket-per-role split of a dapp backend's layout. Path-style\n * addressing turns each bucket into a subfolder of the one origin \u2014\n * `/state`, `/data`, `/index`:\n *\n *   - `data`  \u2014 immutable, append-only facts (the source of truth)\n *   - `state` \u2014 mutable current derived view, rebuilt by the DappActor\n *   - `index` \u2014 query-optimized derived views, rebuilt by the DappActor\n */\nexport const DAPP_BUCKETS = ['state', 'data', 'index'] as const\nexport type DappBucket = typeof DAPP_BUCKETS[number]\n\nconst DEFAULT_HOST = '127.0.0.1'\nconst DEFAULT_PORT = 8801\n\n/** Allow browser dapp clients to read the layout cross-origin. */\nconst CORS_ALLOW_READS = `<CORSConfiguration>\n  <CORSRule>\n    <AllowedOrigin>*</AllowedOrigin>\n    <AllowedMethod>GET</AllowedMethod>\n    <AllowedMethod>HEAD</AllowedMethod>\n    <AllowedHeader>*</AllowedHeader>\n  </CORSRule>\n</CORSConfiguration>`\n\nexport interface DappServerOptions {\n  backing: DappBacking\n  host?: string\n  port?: number\n  publicHost?: string\n  silent?: boolean\n  tls?: {\n    cert: string | Buffer\n    key: string | Buffer\n  }\n}\n\nexport interface RunningDappServer {\n  baseUrl: string\n  port: number\n  close(): Promise<void>\n}\n\n/**\n * Boots an S3-compatible server (s3rver) pre-configured with the three dapp\n * layout buckets. Writers use the S3 API (any credentials are accepted);\n * readers fetch `/{bucket}/{layout-path}` over HTTP or optional TLS.\n *\n * DEV ONLY \u2014 this server is a local development fixture, not a production\n * dapp host. It intentionally skips the production concerns the datalake and\n * signing-pool planes carry (auth, metrics, durable multi-instance storage):\n * any S3 credentials are accepted and the only backing is an ephemeral temp\n * directory. Production dapps stay on real object storage (S3/R2) behind the\n * standard sub-domain layout.\n */\nexport async function startDappServer(options: DappServerOptions): Promise<RunningDappServer> {\n  const host = options.host ?? DEFAULT_HOST\n  const publicHost = options.publicHost ?? host\n  await options.backing.prepare()\n  const server = new S3rver({\n    address: host,\n    allowMismatchedSignatures: true,\n    cert: options.tls?.cert,\n    configureBuckets: DAPP_BUCKETS.map(name => ({ name, configs: [CORS_ALLOW_READS] })),\n    directory: options.backing.directory,\n    key: options.tls?.key,\n    port: options.port ?? DEFAULT_PORT,\n    silent: options.silent ?? false,\n    vhostBuckets: false,\n  })\n  try {\n    const { port } = await server.run()\n    return {\n      baseUrl: `${options.tls === undefined ? 'http' : 'https'}://${publicHost}:${port}`,\n      port,\n      close: async (): Promise<void> => {\n        await server.close()\n        await options.backing.cleanup()\n      },\n    }\n  } catch (error) {\n    await options.backing.cleanup()\n    throw error\n  }\n}\n"],
+  "mappings": ";AAAA,SAAS,SAAS,UAAU;AAC5B,SAAS,cAAc;AACvB,OAAO,UAAU;AAEV,IAAM,gBAAgB,CAAC,QAAQ;AAG/B,SAAS,kBAAkB,OAAyC;AACzE,SAAQ,cAAoC,SAAS,KAAK;AAC5D;AAkBO,SAAS,sBAAmC;AACjD,MAAI;AACJ,SAAO;AAAA,IACL,aAAa;AAAA,IACb,IAAI,YAAoB;AACtB,UAAI,QAAQ,OAAW,OAAM,IAAI,MAAM,6BAA6B;AACpE,aAAO;AAAA,IACT;AAAA,IACA,MAAM,UAAyB;AAC7B,cAAQ,MAAM,QAAQ,KAAK,KAAK,OAAO,GAAG,aAAa,CAAC;AAAA,IAC1D;AAAA,IACA,MAAM,UAAyB;AAC7B,UAAI,QAAQ,OAAW,OAAM,GAAG,KAAK,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AACrE,YAAM;AAAA,IACR;AAAA,EACF;AACF;AAEO,SAAS,eAAe,MAAoC;AACjE,UAAQ,MAAM;AAAA,IACZ,KAAK,UAAU;AACb,aAAO,oBAAoB;AAAA,IAC7B;AAAA,EACF;AACF;;;ACnDA,OAAO,YAAY;AAaZ,IAAM,eAAe,CAAC,SAAS,QAAQ,OAAO;AAGrD,IAAM,eAAe;AACrB,IAAM,eAAe;AAGrB,IAAM,mBAAmB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuCzB,eAAsB,gBAAgB,SAAwD;AAC5F,QAAM,OAAO,QAAQ,QAAQ;AAC7B,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,QAAQ,QAAQ,QAAQ;AAC9B,QAAM,SAAS,IAAI,OAAO;AAAA,IACxB,SAAS;AAAA,IACT,2BAA2B;AAAA,IAC3B,MAAM,QAAQ,KAAK;AAAA,IACnB,kBAAkB,aAAa,IAAI,WAAS,EAAE,MAAM,SAAS,CAAC,gBAAgB,EAAE,EAAE;AAAA,IAClF,WAAW,QAAQ,QAAQ;AAAA,IAC3B,KAAK,QAAQ,KAAK;AAAA,IAClB,MAAM,QAAQ,QAAQ;AAAA,IACtB,QAAQ,QAAQ,UAAU;AAAA,IAC1B,cAAc;AAAA,EAChB,CAAC;AACD,MAAI;AACF,UAAM,EAAE,KAAK,IAAI,MAAM,OAAO,IAAI;AAClC,WAAO;AAAA,MACL,SAAS,GAAG,QAAQ,QAAQ,SAAY,SAAS,OAAO,MAAM,UAAU,IAAI,IAAI;AAAA,MAChF;AAAA,MACA,OAAO,YAA2B;AAChC,cAAM,OAAO,MAAM;AACnB,cAAM,QAAQ,QAAQ,QAAQ;AAAA,MAChC;AAAA,IACF;AAAA,EACF,SAAS,OAAO;AACd,UAAM,QAAQ,QAAQ,QAAQ;AAC9B,UAAM;AAAA,EACR;AACF;",
+  "names": []
+}

package/dist/node/startDappServer.d.ts

@@ -0,0 +1,42 @@
+import type { DappBacking } from './DappBacking.ts';
+/**
+ * The bucket-per-role split of a dapp backend's layout. Path-style
+ * addressing turns each bucket into a subfolder of the one origin —
+ * `/state`, `/data`, `/index`:
+ *
+ *   - `data`  — immutable, append-only facts (the source of truth)
+ *   - `state` — mutable current derived view, rebuilt by the DappActor
+ *   - `index` — query-optimized derived views, rebuilt by the DappActor
+ */
+export declare const DAPP_BUCKETS: readonly ["state", "data", "index"];
+export type DappBucket = typeof DAPP_BUCKETS[number];
+export interface DappServerOptions {
+    backing: DappBacking;
+    host?: string;
+    port?: number;
+    publicHost?: string;
+    silent?: boolean;
+    tls?: {
+        cert: string | Buffer;
+        key: string | Buffer;
+    };
+}
+export interface RunningDappServer {
+    baseUrl: string;
+    port: number;
+    close(): Promise<void>;
+}
+/**
+ * Boots an S3-compatible server (s3rver) pre-configured with the three dapp
+ * layout buckets. Writers use the S3 API (any credentials are accepted);
+ * readers fetch `/{bucket}/{layout-path}` over HTTP or optional TLS.
+ *
+ * DEV ONLY — this server is a local development fixture, not a production
+ * dapp host. It intentionally skips the production concerns the datalake and
+ * signing-pool planes carry (auth, metrics, durable multi-instance storage):
+ * any S3 credentials are accepted and the only backing is an ephemeral temp
+ * directory. Production dapps stay on real object storage (S3/R2) behind the
+ * standard sub-domain layout.
+ */
+export declare function startDappServer(options: DappServerOptions): Promise<RunningDappServer>;
+//# sourceMappingURL=startDappServer.d.ts.map

package/dist/node/startDappServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startDappServer.d.ts","sourceRoot":"","sources":["../../src/startDappServer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,qCAAsC,CAAA;AAC/D,MAAM,MAAM,UAAU,GAAG,OAAO,YAAY,CAAC,MAAM,CAAC,CAAA;AAepD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,WAAW,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE;QACJ,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;QACrB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KACrB,CAAA;CACF;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6B5F"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ariestools/aries-dapp-serve",
+  "version": "0.1.7",
+  "description": "Aries dapp REST server: serves a dapp backend's S3 layout from one origin with /state, /data, /index subfolders",
+  "keywords": [
+    "ariestools",
+    "xl1",
+    "xyo",
+    "dapp",
+    "s3",
+    "typescript"
+  ],
+  "homepage": "https://ariestools.ai",
+  "license": "LGPL-3.0-only",
+  "author": {
+    "name": "Arie Trouw",
+    "email": "support@ariestools.ai",
+    "url": "https://ariestools.ai"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "s3rver": "~3.7.1"
+  },
+  "devDependencies": {
+    "@ariestools/tsconfig": "~8.7.16",
+    "@aws-sdk/client-s3": "~3.1090.0",
+    "@types/node": "~26.1.1",
+    "@types/s3rver": "~3.7.4",
+    "typescript": "~6.0.3",
+    "vite": "~8.1.5",
+    "vitest": "~4.1.10"
+  },
+  "engines": {
+    "node": ">=18.17.1"
+  },
+  "engineStrict": true
+}