@datafn/server 0.0.3 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -23,6 +23,7 @@ npm install @datafn/server @datafn/core @superfunctions/db @superfunctions/http
23
23
  | **Sync: Seed** | Seed data into the database |
24
24
  | **Authorization** | Per-action authorization hook |
25
25
  | **Multi-User Isolation** | Per-user/tenant namespace isolation for change tracking |
26
+ | **Multi-Region Gateway** | Atomic tenant placement, pre-execution cell fencing, signed internal forwarding, bounded stale-epoch retry, and controlled moves |
26
27
  | **REST Endpoints** | Optional REST wrappers over DFQL (GET/POST/PATCH/DELETE) |
27
28
  | **WebSocket** | Real-time cursor broadcast for live updates |
28
29
  | **Plugins** | Hook into queries, mutations, and sync on the server side |
@@ -30,6 +31,40 @@ npm install @datafn/server @datafn/core @superfunctions/db @superfunctions/http
30
31
  | **Payload Limits** | Configurable max query limits, transaction steps, and payload size |
31
32
  | **KV Resource** | Built-in key-value resource auto-included in schema |
32
33
 
34
+ Multi-region gateway mode is opt-in and keeps ownership separate from the
35
+ permission-directory projection. See
36
+ [`multi-region-gateway.mdx`](../docs/content/docs/documentation/multi-region-gateway.mdx)
37
+ for configuration, error, WebSocket, consistency, migration, and operations
38
+ contracts.
39
+
40
+ ### Initial region placement
41
+
42
+ DataFn provides reusable region selection without embedding a product's data
43
+ residency or capacity policy:
44
+
45
+ ```typescript
46
+ import {
47
+ readDatafnCloudflarePlacementLocation,
48
+ selectDatafnPlacementRegion,
49
+ } from "@datafn/server/placement";
50
+
51
+ const decision = selectDatafnPlacementRegion({
52
+ candidates: regions,
53
+ location: readDatafnCloudflarePlacementLocation(request),
54
+ constraints: [
55
+ (region) => allowedRegionIds.includes(region.regionId),
56
+ (region) => healthyRegionIds.has(region.regionId),
57
+ ],
58
+ });
59
+ ```
60
+
61
+ An eligible explicit preference wins first, trusted coordinates or continent
62
+ metadata rank the remaining regions by distance, and an optional `stableKey`
63
+ enables deterministic fallback. The returned decision records which source was
64
+ used. Applications remain responsible for defining eligible regions, collecting
65
+ explicit organization choices, and atomically claiming the resulting namespace
66
+ through the placement directory.
67
+
33
68
  ---
34
69
 
35
70
  ## Quick Start
@@ -55,7 +90,7 @@ const server = await createDatafnServer({
55
90
  },
56
91
  ],
57
92
  },
58
- db: drizzleAdapter({ db: myDrizzleInstance, dialect: "postgres" }),
93
+ database: drizzleAdapter({ db: myDrizzleInstance, dialect: "postgres" }),
59
94
  authorize: async (ctx, action, payload) => {
60
95
  return true; // Allow all (replace with real logic)
61
96
  },
@@ -78,7 +113,7 @@ interface DatafnServerConfig<TContext = any> {
78
113
  schema: DatafnSchema;
79
114
 
80
115
  /** Database adapter (e.g. drizzleAdapter, memoryAdapter) */
81
- db?: Adapter;
116
+ database?: Adapter;
82
117
 
83
118
  /** Server-side plugins */
84
119
  plugins?: DatafnPlugin[];
@@ -95,6 +130,9 @@ interface DatafnServerConfig<TContext = any> {
95
130
  payload: unknown,
96
131
  ) => Promise<boolean> | boolean;
97
132
 
133
+ /** Static request context or a request-scoped context factory. */
134
+ context?: TContext | ((request: Request) => Promise<TContext> | TContext);
135
+
98
136
  /** Configurable limits */
99
137
  limits?: {
100
138
  /** Maximum number of records per query (default: 100) */
@@ -122,6 +160,12 @@ interface DatafnServerConfig<TContext = any> {
122
160
  getContext: (ctx: TContext) => AuthContext | Promise<AuthContext>;
123
161
  };
124
162
 
163
+ /** Trusted namespace and optional actor derivation from request context. */
164
+ namespaceProvider?: {
165
+ getNamespace: (ctx: TContext) => string | Promise<string>;
166
+ getActorId?: (ctx: TContext) => string | undefined | Promise<string | undefined>;
167
+ };
168
+
125
169
  /**
126
170
  * Redis adapter for atomic operations (serverSeq, rate limiting, caching).
127
171
  * Used when dbMapping.serverseq = "redis".
@@ -563,7 +607,7 @@ Isolate change tracking per user or tenant. Each namespace gets its own `serverS
563
607
  ```typescript
564
608
  const server = await createDatafnServer({
565
609
  schema,
566
- db: adapter,
610
+ database: adapter,
567
611
  authContextProvider: {
568
612
  getContext: (ctx) => ({
569
613
  userId: ctx.session?.userId,
@@ -595,13 +639,13 @@ The server uses a `SequenceStore` for generating monotonically increasing sequen
595
639
  // Default: use main database
596
640
  const server = await createDatafnServer({
597
641
  schema,
598
- db: adapter,
642
+ database: adapter,
599
643
  });
600
644
 
601
645
  // Redis for high-throughput atomic INCR
602
646
  const server = await createDatafnServer({
603
647
  schema,
604
- db: adapter,
648
+ database: adapter,
605
649
  redis: myRedisAdapter,
606
650
  dbMapping: { serverseq: "redis" },
607
651
  });
@@ -609,7 +653,7 @@ const server = await createDatafnServer({
609
653
  // KV store (e.g. Cloudflare KV, DynamoDB)
610
654
  const server = await createDatafnServer({
611
655
  schema,
612
- db: adapter,
656
+ database: adapter,
613
657
  kvStore: myKVAdapter,
614
658
  dbMapping: { serverseq: "kv" },
615
659
  });
@@ -647,7 +691,7 @@ Enable REST wrappers alongside DFQL endpoints:
647
691
  ```typescript
648
692
  const server = await createDatafnServer({
649
693
  schema,
650
- db: adapter,
694
+ database: adapter,
651
695
  rest: true, // Enable REST endpoints
652
696
  });
653
697
  ```
@@ -668,7 +712,7 @@ const server = await createDatafnServer({
668
712
  The server exposes a WebSocket handler for real-time cursor broadcasts:
669
713
 
670
714
  ```typescript
671
- const server = await createDatafnServer({ schema, db: adapter });
715
+ const server = await createDatafnServer({ schema, database: adapter });
672
716
 
673
717
  // Wire WebSocket connections to server handler
674
718
  wss.on("connection", (ws) => {
@@ -702,7 +746,7 @@ const auditPlugin: DatafnPlugin = {
702
746
 
703
747
  const server = await createDatafnServer({
704
748
  schema,
705
- db: adapter,
749
+ database: adapter,
706
750
  plugins: [auditPlugin],
707
751
  });
708
752
  ```