effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/unstable/eventlog/EventLogMessage.ts

@@ -1,4 +1,18 @@
 /**
+ * Defines the wire messages used by event-log remotes to authenticate clients,
+ * write event batches, and stream changes back to replicas.
+ *
+ * This module is the protocol boundary between `EventLogRemote` clients and
+ * event-log servers: it provides schemas for store identifiers, protocol
+ * errors, session handshake payloads, authenticated RPCs, and the msgpack
+ * payloads used to carry encrypted or plaintext journal entries.
+ *
+ * Event batches are serialized as binary payloads before transport. Small
+ * payloads can be sent as a single frame, while larger payloads are split into
+ * `ChunkedMessage` parts and must be reassembled by message id after every part
+ * has arrived. Transports should preserve `Uint8Array` bytes exactly and avoid
+ * treating msgpack data as text.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyArray, NonEmptyReadonlyArray } from "../../Array.ts"
@@ -14,32 +28,45 @@ import type { Identity } from "./EventLog.ts"
 import { EncryptedEntry, EncryptedRemoteEntry } from "./EventLogEncryption.ts"
 
 /**
- * @since 4.0.0
+ * Type-level identifier used to brand event-log store ids.
+ *
  * @category StoreId
+ * @since 4.0.0
  */
 export type StoreIdTypeId = "effect/eventlog/EventLog/StoreId"
 
 /**
- * @since 4.0.0
+ * Runtime brand identifier for event-log store ids.
+ *
  * @category StoreId
+ * @since 4.0.0
  */
 export const StoreIdTypeId: StoreIdTypeId = "effect/eventlog/EventLog/StoreId"
 
 /**
- * @since 4.0.0
+ * Branded string identifying a logical event-log store.
+ *
  * @category StoreId
+ * @since 4.0.0
  */
 export type StoreId = string & Brand<StoreIdTypeId>
 
 /**
- * @since 4.0.0
+ * Schema for branded event-log store ids.
+ *
  * @category StoreId
+ * @since 4.0.0
  */
 export const StoreId = Schema.String.pipe(Schema.brand(StoreIdTypeId))
 
 /**
- * @since 4.0.0
+ * Structured error returned by event-log remote RPCs.
+ *
+ * It records the request tag, optional identity and store information, a protocol
+ * error code, and a human-readable message.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class EventLogProtocolError extends Schema.TaggedErrorClass<EventLogProtocolError>(
   "effect/eventlog/EventLogRemote/ProtocolError"
@@ -52,8 +79,11 @@ export class EventLogProtocolError extends Schema.TaggedErrorClass<EventLogProto
 }) {}
 
 /**
- * @since 4.0.0
+ * RPC middleware that authenticates event-log requests and provides the client
+ * `Identity` to authenticated handlers.
+ *
  * @category Middleware
+ * @since 4.0.0
  */
 export class EventLogAuthentication extends RpcMiddleware.Service<EventLogAuthentication, {
   provides: Identity
@@ -62,8 +92,13 @@ export class EventLogAuthentication extends RpcMiddleware.Service<EventLogAuthen
 }) {}
 
 /**
- * @since 4.0.0
+ * Response sent by the remote server during the authentication handshake.
+ *
+ * It contains the server remote id and a challenge that must be signed by the
+ * client.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class HelloResponse extends Schema.Class<HelloResponse>("effect/eventlog/EventLogRemote/HelloResponse")({
   remoteId: RemoteId,
@@ -71,16 +106,21 @@ export class HelloResponse extends Schema.Class<HelloResponse>("effect/eventlog/
 }) {}
 
 /**
- * @since 4.0.0
+ * RPC used to start an event-log remote session and receive a `HelloResponse`.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class HelloRpc extends Rpc.make("EventLog.Hello", {
   success: HelloResponse
 }) {}
 
 /**
- * @since 4.0.0
+ * Authentication request containing the client public key, Ed25519 signing public
+ * key, signature over the session challenge payload, and algorithm name.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class Authenticate extends Schema.Class<Authenticate>("effect/eventlog/EventLogRemote/Authenticate")({
   publicKey: Schema.String,
@@ -90,8 +130,10 @@ export class Authenticate extends Schema.Class<Authenticate>("effect/eventlog/Ev
 }) {}
 
 /**
- * @since 4.0.0
+ * RPC used to authenticate a remote event-log session after `HelloRpc`.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class AuthenticateRpc extends Rpc.make("EventLog.Authenticate", {
   payload: Authenticate,
@@ -99,8 +141,10 @@ export class AuthenticateRpc extends Rpc.make("EventLog.Authenticate", {
 }) {}
 
 /**
- * @since 4.0.0
+ * Transport message containing an entire encoded event-log payload in one frame.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class SingleMessage
   extends Schema.TaggedClass<SingleMessage>("effect/eventlog/EventLogRemote/SingleMessage")("Single", {
@@ -109,8 +153,13 @@ export class SingleMessage
 {}
 
 /**
- * @since 4.0.0
+ * Transport message for one part of a large encoded event-log payload.
+ *
+ * Use `split` to divide data into chunks and `join` to reassemble all chunks with
+ * the same id once every part has arrived.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class ChunkedMessage
   extends Schema.TaggedClass<ChunkedMessage>("effect/eventlog/EventLogRemote/ChunkedMessage")("Chunked", {
@@ -130,6 +179,8 @@ export class ChunkedMessage
   }
 
   /**
+   * Splits binary event-log message data into numbered chunks.
+   *
    * @since 4.0.0
    */
   static split(id: number, data: Uint8Array): NonEmptyReadonlyArray<ChunkedMessage> {
@@ -148,6 +199,8 @@ export class ChunkedMessage
   }
 
   /**
+   * Reassembles all chunks for a message id into the original binary payload.
+   *
    * @since 4.0.0
    */
   static join(
@@ -186,8 +239,10 @@ export class ChunkedMessage
 }
 
 /**
- * @since 4.0.0
+ * Authenticated RPC for sending one chunk of a large encoded write payload.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class WriteChunkedRpc extends Rpc.make("EventLog.WriteChunked", {
   payload: ChunkedMessage,
@@ -195,8 +250,13 @@ export class WriteChunkedRpc extends Rpc.make("EventLog.WriteChunked", {
 }).middleware(EventLogAuthentication) {}
 
 /**
- * @since 4.0.0
+ * Msgpack-encodable payload for writing encrypted entries to a remote store.
+ *
+ * It includes the client public key, target store id, AES-GCM initialization
+ * vector, and encrypted entries.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class WriteEntries extends Schema.Class<WriteEntries>("effect/eventlog/EventLogRemote/WriteEntries")({
   publicKey: Schema.String,
@@ -213,8 +273,10 @@ export class WriteEntries extends Schema.Class<WriteEntries>("effect/eventlog/Ev
 }
 
 /**
- * @since 4.0.0
+ * Msgpack-encodable payload for writing plaintext entries to a remote store.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class WriteEntriesUnencrypted
   extends Schema.Class<WriteEntriesUnencrypted>("effect/eventlog/EventLogRemote/WriteEntriesUnencrypted")({
@@ -232,8 +294,11 @@ export class WriteEntriesUnencrypted
 }
 
 /**
- * @since 4.0.0
+ * Authenticated RPC for sending an encoded write payload that fits in one
+ * message.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class WriteSingleRpc extends Rpc.make("EventLog.WriteSingle", {
   payload: {
@@ -243,8 +308,14 @@ export class WriteSingleRpc extends Rpc.make("EventLog.WriteSingle", {
 }).middleware(EventLogAuthentication) {}
 
 /**
- * @since 4.0.0
+ * Authenticated streaming RPC for reading remote event-log changes for a public
+ * key and store id starting at a sequence number.
+ *
+ * Responses are encoded as either `SingleMessage` values or `ChunkedMessage`
+ * parts.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class ChangesRpc extends Rpc.make("EventLog.Changes", {
   payload: {
@@ -265,8 +336,11 @@ export class ChangesRpc extends Rpc.make("EventLog.Changes", {
 }
 
 /**
- * @since 4.0.0
+ * RPC group containing the event-log remote handshake, authentication, write, and
+ * changes endpoints.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class EventLogRemoteRpcs extends RpcGroup.make(
   HelloRpc,

package/src/unstable/eventlog/EventLogRemote.ts

@@ -1,4 +1,23 @@
 /**
+ * Client-side remote replica support for writing event-log entries and
+ * receiving change streams over the event-log RPC protocol.
+ *
+ * This module builds `EventLogRemote` services backed by `EventLogRemoteRpcs`.
+ * It is used by local event logs that need to replicate entries to another
+ * journal, subscribe to remote changes from a sequence number, or run effects
+ * only after the current event-log identity has completed the remote
+ * authentication handshake. The encrypted constructor is the default choice for
+ * synchronizing browser, edge, or service replicas across an untrusted network,
+ * while the unencrypted constructor is intended for trusted transports or tests.
+ *
+ * Remote sessions begin with `Hello` and `Authenticate`, cache authentication by
+ * identity public key, and retry forbidden responses by refreshing the handshake.
+ * The RPC transport must preserve a stable client session across hello,
+ * authentication, writes, and change streams. Entries and change batches may be
+ * split into protocol chunks, so callers should treat `changes` as a scoped
+ * streaming queue and rely on the remote `Registry` registration instead of
+ * manually sharing partially assembled payloads between sessions.
+ *
  * @since 4.0.0
  */
 import * as Cache from "../../Cache.ts"
@@ -32,8 +51,13 @@ import { encodeSessionAuthPayload, signSessionAuthPayloadBytes } from "./EventLo
 import { makeGetIdentityRootSecretMaterial } from "./internal/identityRootSecretDerivation.ts"
 
 /**
- * @since 4.0.0
+ * Service representing a remote event-log replica.
+ *
+ * It can write local entries to the remote, stream remote changes from a sequence
+ * number, and run effects only after the supplied identity has authenticated.
+ *
  * @category models
+ * @since 4.0.0
  */
 export class EventLogRemote extends Context.Service<EventLogRemote, {
   readonly id: RemoteId
@@ -53,8 +77,11 @@ export class EventLogRemote extends Context.Service<EventLogRemote, {
 }>()("effect/eventlog/EventLogRemote") {}
 
 /**
- * @since 4.0.0
+ * Error raised by `EventLogRemote` operations, recording the failed method and
+ * underlying cause.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class EventLogRemoteError extends Data.TaggedError("EventLogRemoteError")<{
   readonly method: string
@@ -88,8 +115,10 @@ const makeAuthenticate = Effect.fnUntraced(function*(options: {
 })
 
 /**
- * @since 4.0.0
+ * Typed RPC client service for the `EventLogRemoteRpcs` protocol.
+ *
  * @category RpcClient
+ * @since 4.0.0
  */
 export class EventLogRemoteClient extends Context.Service<
   EventLogRemoteClient,
@@ -106,8 +135,15 @@ export class EventLogRemoteClient extends Context.Service<
 }
 
 /**
- * @since 4.0.0
+ * Creates an `EventLogRemote` from custom write encoding and change decoding
+ * functions.
+ *
+ * The remote performs the hello/authentication handshake, retries after forbidden
+ * responses by re-authenticating, chunks large writes, and registers itself with
+ * the `Registry` for the current scope.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeWith = Effect.fnUntraced(function*({ encodeWrite, decodeChanges }: {
   readonly encodeWrite: (options: {
@@ -251,8 +287,11 @@ class IdentityService extends Context.Service<Identity, Identity["Service"]>()(
 ) {}
 
 /**
- * @since 4.0.0
+ * Creates an `EventLogRemote` that encrypts outgoing entries and decrypts
+ * incoming changes with `EventLogEncryption`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeEncrypted = Effect.gen(function*(): Effect.fn.Return<
   EventLogRemote["Service"],
@@ -284,8 +323,10 @@ export const makeEncrypted = Effect.gen(function*(): Effect.fn.Return<
 })
 
 /**
- * @since 4.0.0
+ * Creates an `EventLogRemote` that sends and receives plaintext entry payloads.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const makeUnencrypted: Effect.Effect<
   EventLogRemote["Service"],
@@ -302,8 +343,11 @@ export const makeUnencrypted: Effect.Effect<
 })
 
 /**
- * @since 4.0.0
+ * Provides an encrypted `EventLogRemote` using the remote RPC client and the
+ * default Web Crypto encryption layer.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerEncrypted: Layer.Layer<
   EventLogRemote,
@@ -315,8 +359,10 @@ export const layerEncrypted: Layer.Layer<
 )
 
 /**
- * @since 4.0.0
+ * Provides an unencrypted `EventLogRemote` using the remote RPC client.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerUnencrypted: Layer.Layer<
   EventLogRemote,

package/src/unstable/eventlog/EventLogServer.ts

@@ -1,4 +1,20 @@
 /**
+ * Server-side RPC handlers for accepting remote event-log writes and streaming
+ * changes back to authenticated clients.
+ *
+ * This module is the protocol glue used by concrete event-log servers: it
+ * performs the hello / authenticate challenge flow, attaches the authenticated
+ * `EventLog.Identity` to subsequent RPC requests, reassembles chunked writes,
+ * and chunks large change payloads before they are sent to clients. It is useful
+ * when exposing an event-log replica over HTTP-backed RPC, for example to sync
+ * browser, edge, or service replicas with a central journal.
+ *
+ * The authentication state is tied to the RPC client session annotations, so the
+ * transport must preserve a stable client session between `Hello`,
+ * `Authenticate`, writes, and change streams. Deployments should run the endpoint
+ * over TLS, avoid exposing unauthenticated write or changes routes, and persist
+ * session-auth key bindings with the same trust boundary as the event-log data.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -29,8 +45,13 @@ import {
 import * as EventLogSessionAuth from "./EventLogSessionAuth.ts"
 
 /**
- * @since 4.0.0
+ * Provides RPC authentication middleware that reads the authenticated
+ * `EventLog.Identity` from client annotations.
+ *
+ * Requests without an identity fail with a forbidden `EventLogProtocolError`.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerAuthMiddleware: Layer.Layer<
   EventLogAuthentication
@@ -48,8 +69,14 @@ export const layerAuthMiddleware: Layer.Layer<
 })
 
 /**
- * @since 4.0.0
+ * Creates the shared RPC handlers for the event-log remote protocol.
+ *
+ * The layer manages hello challenges, verifies session authentication, reassembles
+ * chunked writes, delegates write and change handling to the supplied callbacks,
+ * and frames large change payloads into chunks.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerRpcHandlers = (options: {
   readonly remoteId: RemoteId
@@ -184,8 +211,11 @@ export const layerRpcHandlers = (options: {
   )
 
 /**
- * @since 4.0.0
+ * Client annotation storing partial `ChunkedMessage` data while chunked writes are
+ * being reassembled.
+ *
  * @category ChunkedMessage state
+ * @since 4.0.0
  */
 export class ChunkedMessageState extends Context.Reference<
   Map<number, {

package/src/unstable/eventlog/EventLogServerEncrypted.ts

@@ -1,4 +1,24 @@
 /**
+ * Server-side RPC layers and storage contracts for encrypted event-log
+ * replication.
+ *
+ * This module is used by encrypted `EventLogRemote` clients that need a remote
+ * synchronization endpoint without exposing plaintext events to the server. The
+ * server stores ciphertext, initialization vectors, entry ids, and remote
+ * sequence numbers keyed by the client's public key and store id, then streams
+ * encrypted changes back to clients so they can decrypt locally with their
+ * identity private key material. This makes it suitable for offline-first
+ * synchronization, multi-device replication, and hosted backends where the
+ * transport or storage layer should not inspect event payloads.
+ *
+ * The server does not derive or hold encryption keys. It treats public keys as
+ * log identities, persists one session authentication binding per public key,
+ * and reuses the initialization vector supplied with each encrypted write
+ * request for the entries in that batch. Persisted remote ids, session signing
+ * key bindings, ciphertext, IVs, and sequence numbers are therefore part of the
+ * encrypted replication protocol and should be kept stable by durable storage
+ * implementations.
+ *
  * @since 4.0.0
  */
 import * as Uuid from "uuid"
@@ -19,8 +39,14 @@ import { ChangesRpc, EventLogProtocolError, EventLogRemoteRpcs, type StoreId, Wr
 import * as EventLogServer from "./EventLogServer.ts"
 
 /**
- * @since 4.0.0
+ * Provides RPC handlers for the encrypted event-log server.
+ *
+ * Incoming encrypted write payloads are decoded and persisted through `Storage`;
+ * change streams read encrypted entries from storage and encode them for the
+ * remote protocol.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layerRpcHandlers = Layer.unwrap(Effect.gen(function*() {
   const storage = yield* Storage
@@ -70,16 +96,21 @@ export const layerRpcHandlers = Layer.unwrap(Effect.gen(function*() {
 }))
 
 /**
- * @since 4.0.0
+ * Provides an encrypted event-log RPC server using `EventLogRemoteRpcs` and the
+ * encrypted server RPC handlers.
+ *
  * @category Layers
+ * @since 4.0.0
  */
 export const layer: Layer.Layer<never, never, RpcServer.Protocol | Storage> = RpcServer.layer(EventLogRemoteRpcs).pipe(
   Layer.provide(layerRpcHandlers)
 )
 
 /**
- * @since 4.0.0
+ * Encrypted entry representation persisted by the encrypted event-log server.
+ *
  * @category storage
+ * @since 4.0.0
  */
 export class PersistedEntry extends Schema.Class<PersistedEntry>(
   "effect/eventlog/EventLogServerEncrypted/PersistedEntry"
@@ -89,6 +120,8 @@ export class PersistedEntry extends Schema.Class<PersistedEntry>(
   encryptedEntry: Transferable.Uint8Array
 }) {
   /**
+   * String representation of the encrypted entry id.
+   *
    * @since 4.0.0
    */
   get entryIdString(): string {
@@ -97,8 +130,14 @@ export class PersistedEntry extends Schema.Class<PersistedEntry>(
 }
 
 /**
- * @since 4.0.0
+ * Storage service used by the encrypted event-log server.
+ *
+ * It provides the server remote id, stores session authentication bindings,
+ * persists encrypted entries, and streams encrypted changes for a public key and
+ * store id.
+ *
  * @category storage
+ * @since 4.0.0
  */
 export class Storage extends Context.Service<Storage, {
   readonly getId: Effect.Effect<RemoteId>
@@ -119,8 +158,13 @@ export class Storage extends Context.Service<Storage, {
 }>()("effect/eventlog/EventLogServer/Storage") {}
 
 /**
- * @since 4.0.0
+ * Creates an in-memory encrypted server `Storage`.
+ *
+ * Data, session authentication bindings, and streams are process-local and are
+ * released with the surrounding scope.
+ *
  * @category storage
+ * @since 4.0.0
  */
 export const makeStorageMemory: Effect.Effect<Storage["Service"], never, Scope.Scope> = Effect.gen(function*() {
   const knownIds = new Map<string, Map<string, number>>()
@@ -193,8 +237,10 @@ export const makeStorageMemory: Effect.Effect<Storage["Service"], never, Scope.S
 })
 
 /**
- * @since 4.0.0
+ * Provides encrypted server `Storage` using the in-memory implementation.
+ *
  * @category storage
+ * @since 4.0.0
  */
 export const layerStorageMemory: Layer.Layer<Storage> = Layer.effect(Storage)(makeStorageMemory)