foldkit-remote-server 0.1.0 → 0.2.0
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 +78 -44
- package/package.json +14 -3
package/README.md
CHANGED
|
@@ -1,16 +1,36 @@
|
|
|
1
1
|
# `foldkit-remote-server`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
Answers the requests a
|
|
4
|
+
[`foldkit-remote`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote)
|
|
5
|
+
client makes. You write one **Source** per entity, query, and mutation — plain
|
|
6
|
+
Effect functions that load rows — and this package compiles them into the
|
|
7
|
+
`RemoteRpc` handlers: it groups and de-duplicates the ids a client asked for,
|
|
8
|
+
drops the fields a principal may not read, resolves a nested selection level by
|
|
9
|
+
level through each entity's own Source, and normalizes the results into the
|
|
10
|
+
patches the client's store reconciles.
|
|
11
|
+
|
|
12
|
+
Reach for it when the server is yours and you want the client's field-level
|
|
13
|
+
selections honoured end to end, with authorization enforced where the field
|
|
14
|
+
names are still known rather than in the view. It owns no HTTP, WebSockets,
|
|
15
|
+
serialization, authentication protocol, or database connection: `principal` is
|
|
16
|
+
resolved outside and passed in, and a Source's database is an Effect requirement
|
|
17
|
+
the Source declares, not something this package holds.
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pnpm add foldkit-remote-server
|
|
23
|
+
```
|
|
7
24
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
dependencies stay in the Effect environment instead of being captured.
|
|
25
|
+
`effect` is a peer dependency; `foldkit-remote` and `foldkit-surface` come with
|
|
26
|
+
it. `foldkit-remote-drizzle` compiles its selections and queries to SQL.
|
|
11
27
|
|
|
12
28
|
## Quick start
|
|
13
29
|
|
|
30
|
+
One entity, one mutation, one query, one live stream, compiled to a layer.
|
|
31
|
+
`loadProjects`, `renameProject`, `projectsPage`, and `projectEvents` are the
|
|
32
|
+
application's own data access; `principal` is whatever authentication resolved.
|
|
33
|
+
|
|
14
34
|
```ts
|
|
15
35
|
import { Effect, Schema } from 'effect'
|
|
16
36
|
import { Entity, Mutation, Query, RemoteRpc } from 'foldkit-remote'
|
|
@@ -67,22 +87,24 @@ const layer = RemoteRpc.toLayer(handlers)
|
|
|
67
87
|
```
|
|
68
88
|
|
|
69
89
|
`handlers(server, principal, options?)` takes a `HandlerOptions<P, R>`:
|
|
70
|
-
`maxIdsPerEntity` (default 1000) bounds
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
90
|
+
`maxIdsPerEntity` (default 1000) bounds how many distinct ids of one entity a
|
|
91
|
+
read batch — or a `liveHub` subscription — may name, `maxDepth` (default 8)
|
|
92
|
+
bounds nested resolution, and `live` is the hub whose signals reach the
|
|
93
|
+
subscriptions this handler registers. In-process, the handlers are a
|
|
94
|
+
`RemoteClient` through `Remote.clientLayer(handlers)`, with whatever the sources
|
|
95
|
+
require supplied by `Layer.provide`.
|
|
75
96
|
|
|
76
97
|
## Sources
|
|
77
98
|
|
|
78
99
|
### `RemoteServer.entity`
|
|
79
100
|
|
|
80
|
-
```
|
|
81
|
-
RemoteServer.entity(
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
Effect
|
|
85
|
-
|
|
101
|
+
```text
|
|
102
|
+
RemoteServer.entity(entity, {
|
|
103
|
+
read: (context: { ids: readonly string[]; fields: readonly string[]
|
|
104
|
+
windows?: Record<string, QueryWindow>; principal: P })
|
|
105
|
+
=> Effect<ReadonlyArray<{ id: string; values: Record<string, unknown> }>, RemoteServerError, R>
|
|
106
|
+
authorize?: (principal: P, fields: readonly string[]) => readonly string[]
|
|
107
|
+
}): EntitySource<P, R>
|
|
86
108
|
```
|
|
87
109
|
|
|
88
110
|
Given the Entity, a request for a field it does not declare never reaches
|
|
@@ -92,16 +114,15 @@ no fields and passes every requested one through.
|
|
|
92
114
|
`read` is called once per entity, id batch, and window per read level: ids are
|
|
93
115
|
batched up to `maxIdsPerEntity`, ids that page a relation differently are read
|
|
94
116
|
separately, and a nested selection reads its next level after the refs arrive.
|
|
95
|
-
`windows` carries the pagination window for each requested relation field. The
|
|
96
|
-
entity: a field the source omits is simply not present,
|
|
97
|
-
the client reflects that.
|
|
117
|
+
`windows` carries the pagination window for each requested relation field. The
|
|
118
|
+
result may be a partial entity: a field the source omits is simply not present,
|
|
119
|
+
and presence metadata on the client reflects that.
|
|
98
120
|
|
|
99
121
|
### `RemoteServer.query`
|
|
100
122
|
|
|
101
|
-
```
|
|
102
|
-
RemoteServer.query(
|
|
103
|
-
Effect
|
|
104
|
-
)
|
|
123
|
+
```text
|
|
124
|
+
RemoteServer.query(query, (context: { input: Input; window: QueryWindow; principal: P })
|
|
125
|
+
=> Effect<QueryPage, RemoteServerError, R>): QuerySource<P, R>
|
|
105
126
|
```
|
|
106
127
|
|
|
107
128
|
`QueryPage` is `{ edges, start, end }`; `start`/`end` are `Boundary` values
|
|
@@ -110,14 +131,12 @@ inferring adjacency from row count.
|
|
|
110
131
|
|
|
111
132
|
### `RemoteServer.mutation`
|
|
112
133
|
|
|
113
|
-
```
|
|
114
|
-
RemoteServer.mutation(
|
|
115
|
-
Effect
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
>,
|
|
120
|
-
)
|
|
134
|
+
```text
|
|
135
|
+
RemoteServer.mutation(mutation, (context: { input: Input; principal: P })
|
|
136
|
+
=> Effect<{ output: Output
|
|
137
|
+
entities?: ReadonlyArray<NormalizedPatch>
|
|
138
|
+
connections?: ReadonlyArray<ConnectionChange> },
|
|
139
|
+
RemoteServerError, R>): MutationSource<P, R>
|
|
121
140
|
```
|
|
122
141
|
|
|
123
142
|
`input` is decoded against the mutation's `Input` schema first, so the callback
|
|
@@ -129,11 +148,11 @@ ones in place: `RemoteServer.prepend(connection, ref)`, `append`, and
|
|
|
129
148
|
|
|
130
149
|
### `RemoteServer.live`
|
|
131
150
|
|
|
132
|
-
```
|
|
133
|
-
RemoteServer.live(
|
|
134
|
-
subscribe: ({ requirements
|
|
135
|
-
Stream
|
|
136
|
-
})
|
|
151
|
+
```text
|
|
152
|
+
RemoteServer.live(entity, {
|
|
153
|
+
subscribe: (context: { requirements: ReadonlyArray<Requirement>; after: number; principal: P })
|
|
154
|
+
=> Stream<LiveChange, RemoteServerError, R>
|
|
155
|
+
}): LiveSource<P, R>
|
|
137
156
|
```
|
|
138
157
|
|
|
139
158
|
`after` is the client's resume cursor; events at or before it are duplicates. The
|
|
@@ -148,21 +167,26 @@ The higher-level signal. A hub tracks each live subscriber's requirements and
|
|
|
148
167
|
principal, so the server says *what changed* and the hub works out *who cares*:
|
|
149
168
|
|
|
150
169
|
```ts
|
|
170
|
+
// `entitySources` is the same array `RemoteServer.make({ entities })` was given.
|
|
151
171
|
const hub = yield* RemoteServer.liveHub(entitySources)
|
|
152
|
-
const handlers = RemoteServer.handlers(
|
|
172
|
+
const handlers = RemoteServer.handlers(Server, principal, { live: hub })
|
|
153
173
|
|
|
154
174
|
// Wherever the data changes (a mutation source, a database trigger):
|
|
155
175
|
yield* hub.changed(Project.ref(projectId), ['status', 'updatedAt'])
|
|
156
176
|
yield* hub.deleted(Project.ref(projectId))
|
|
157
177
|
```
|
|
158
178
|
|
|
179
|
+
`liveHub` and its signals are Effects, so the lines above live inside an
|
|
180
|
+
`Effect.gen`. It needs only the entity sources, so the mutation sources that
|
|
181
|
+
signal it can be built after it.
|
|
182
|
+
|
|
159
183
|
`changed` intersects the fields with what each subscriber selects, re-reads
|
|
160
184
|
that intersection through the entity's own source under the subscriber's
|
|
161
185
|
principal (one read per principal value and window signature; subscribers
|
|
162
186
|
selecting none of the fields do no work), and streams an `EntityPatched`
|
|
163
187
|
carrying only the fields that subscriber may see. A record the source does not
|
|
164
|
-
return for the changed id reaches nobody. `deleted` streams an `EntityDeleted`
|
|
165
|
-
subscribers. Cursors continue from the cursor each subscriber resumed at, so
|
|
188
|
+
return for the changed id reaches nobody. `deleted` streams an `EntityDeleted`
|
|
189
|
+
to the entity's subscribers. Cursors continue from the cursor each subscriber resumed at, so
|
|
166
190
|
the client's duplicate and gap handling is unchanged. A hub and hand-written
|
|
167
191
|
`RemoteServer.live` sources number their events independently; use one or the
|
|
168
192
|
other for a given subscription. Nested relation targets are not subscribed by
|
|
@@ -185,9 +209,10 @@ principal read this semantic field*. Authorization is mandatory, not opt-in:
|
|
|
185
209
|
|
|
186
210
|
## Hardening
|
|
187
211
|
|
|
188
|
-
-
|
|
189
|
-
|
|
190
|
-
|
|
212
|
+
- A read batch is bounded per entity (`maxIdsPerEntity`, default 1000, counted
|
|
213
|
+
across the batch's window groups) and an oversized one fails rather than
|
|
214
|
+
loading unbounded rows; a `liveHub` subscription is bounded the same way. A
|
|
215
|
+
hand-written `RemoteServer.live` source bounds itself.
|
|
191
216
|
- A selection nested past `MAX_RELATION_DEPTH` (8) or naming more than
|
|
192
217
|
`MAX_FIELDS_PER_REQUEST` (256) fields of one entity is refused at decode.
|
|
193
218
|
- Returned field names are filtered with `Object.hasOwn` and accumulated into a
|
|
@@ -214,3 +239,12 @@ principal read this semantic field*. Authorization is mandatory, not opt-in:
|
|
|
214
239
|
connection insert/remove/invalidate events.
|
|
215
240
|
- Database and other runtime dependencies are the Source's Effect requirements,
|
|
216
241
|
not this package's.
|
|
242
|
+
|
|
243
|
+
## See also
|
|
244
|
+
|
|
245
|
+
- [Server-derived state](https://github.com/doeixd/foldkit-plus/blob/main/docs/remote.md) — the mental model for
|
|
246
|
+
both halves.
|
|
247
|
+
- [`foldkit-remote`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote) — the client half this answers; [`foldkit-remote-drizzle`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote-drizzle)
|
|
248
|
+
compiles its selections and queries to SQL.
|
|
249
|
+
- [`examples/kitchen-sink`](https://github.com/doeixd/foldkit-plus/tree/main/examples/kitchen-sink) — the server packages with a live hub, an optimistic
|
|
250
|
+
insert confirmed in place, and retention.
|
package/package.json
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldkit-remote-server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Server sources and handler compilation for foldkit-remote: entities, selection authorization, and normalization.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"foldkit",
|
|
7
|
+
"effect",
|
|
8
|
+
"server-state",
|
|
9
|
+
"rpc",
|
|
10
|
+
"authorization",
|
|
11
|
+
"normalization"
|
|
12
|
+
],
|
|
5
13
|
"type": "module",
|
|
6
14
|
"license": "MIT",
|
|
15
|
+
"publishConfig": {
|
|
16
|
+
"access": "public"
|
|
17
|
+
},
|
|
7
18
|
"author": "Patrick Glenn <doeixd@gmail.com>",
|
|
8
19
|
"repository": {
|
|
9
20
|
"type": "git",
|
|
@@ -27,8 +38,8 @@
|
|
|
27
38
|
"LICENSE"
|
|
28
39
|
],
|
|
29
40
|
"dependencies": {
|
|
30
|
-
"foldkit-remote": "0.
|
|
31
|
-
"foldkit-surface": "0.1.
|
|
41
|
+
"foldkit-remote": "0.2.0",
|
|
42
|
+
"foldkit-surface": "0.1.1"
|
|
32
43
|
},
|
|
33
44
|
"peerDependencies": {
|
|
34
45
|
"effect": "^4.0.0-rc.112"
|