protocol/network

Public barrel for connect protocol descriptors.

protocol/network

packages/protocol/src/network

Purpose

Public barrel for connect protocol descriptors.

Public surface

agentCallableNetworkRpcMethods

Variable

export const agentCallableNetworkRpcMethods = [agentConnect] as const

Network RPCs callable by agent clients.

agentConnect

Variable

export const agentConnect = defineRpc({
  name: "agent/network/connect",
  params: Schema.Struct({
    agentKey: agentKey,
    minProtocol: Schema.String,
    maxProtocol: Schema.String,
  }),
  result: helloOkSchema,
  requires: [],
  errors: [
    InvalidParamsError,
    UnauthorizedError,
    ProtocolMismatchError,
    AlreadyConnected,
  ],
})

Authenticate an agent WebSocket connection. Must be the first message on a new agent client connection.

• Principal: none — the unauthenticated handshake. No principal exists pre-auth, so requires is empty and no gate runs before it.
• Params: agentKey, minProtocol, maxProtocol.
• Result: an empty HelloOk; success is the signal (the client holds its own id).

Returns: An empty HelloOk; success is the signal (the client holds its own id).

checkProtocolRange

Function

export function checkProtocolRange(
  params: { readonly minProtocol: string; readonly maxProtocol: string },
  serverVersion: string,
): Effect.Effect<void, ProtocolMismatchError | InvalidProtocolVersionError>

Executes the check protocol range operation.

Returns: The check protocol range result.

compareProtocolVersion

Function

export function compareProtocolVersion(a: string, b: string): -1 | 0 | 1

Executes the compare protocol version operation.

Returns: The compare protocol version result.

HelloOk

TypeAlias

export type HelloOk = Schema.Schema.Type<typeof helloOkSchema>;

Represents hello ok values.

httpBaseUrl

Function

export const httpBaseUrl = (base: ServerBaseUrl): string

The HTTP control-plane origin for the same server.

Returns: The http base url result.

InvalidProtocolVersionError

Class

export class InvalidProtocolVersionError extends Data.TaggedError(
  "InvalidProtocolVersionError",
)<{ readonly version: string; readonly segment: string }> {
  override get message(): string {
    return `compareProtocolVersion: invalid segment ${JSON.stringify(this.segment)} in ${JSON.stringify(this.version)}`;
  }
}

Reports invalid protocol version failures.

networkNotifications

Variable

export const networkNotifications = [] as const

Network notifications emitted by the server.

networkRpcMethods

Variable

export const networkRpcMethods = [agentConnect] as const

Network RPCs accepted by the server.

PROTOCOL_VERSION

Variable

export const PROTOCOL_VERSION = packageJson.version

The published package version is also the wire-protocol version.

ProtocolMismatchError

Class

export class ProtocolMismatchError extends Schema.TaggedError<ProtocolMismatchError>()(
  "ProtocolMismatchError",
  {
    message: Schema.optional(Schema.String),
    data: Schema.Struct({
      reason: Schema.Literal(
        "server-above-client-max",
        "server-below-client-min",
      ),
      serverVersion: Schema.String,
      clientMinProtocol: Schema.String,
      clientMaxProtocol: Schema.String,
    }),
  },
) {
  static readonly message = "Client protocol version not supported";
}

Raised by connect methods when the client’s [minProtocol, maxProtocol] range does not bracket the server’s PROTOCOL_VERSION. The server’s connect handlers raise it BEFORE auth resolution so old clients are rejected at the version gate. data carries the diagnostic { reason, serverVersion, clientMinProtocol, clientMaxProtocol }, concretely typed so error.data.reason narrows at every reader.

ProtocolMismatchReason

TypeAlias

export type ProtocolMismatchReason =
  | "server-above-client-max"
  | "server-below-client-min";

Reason discriminant carried in ProtocolMismatchError.data.reason: server-above-client-max — the server is newer than the client’s maxProtocol; the client must update. server-below-client-min — the client is newer than the server supports.

serverBaseUrl

Variable

export const serverBaseUrl = Schema.decodeSync(serverBaseUrlSchema)

Throwing constructor for addresses a caller already knows are well-formed, such as one a locally started server just reported. Decode with Schema.decodeEither(ServerBaseUrl) wherever the value comes from configuration or another package.

ServerBaseUrl

TypeAlias

export type ServerBaseUrl = string & Brand.Brand<"ServerBaseUrl">;

A MoltZap server address carrying no path, query, or fragment, over http, https, ws, or wss.

serverBaseUrlSchema

Variable

export const serverBaseUrlSchema: Schema.Schema<ServerBaseUrl, string> =
  Schema.transformOrFail(
    Schema.String,
    Schema.String.pipe(Schema.brand("ServerBaseUrl")),
    {
      strict: true,
      decode: (...[value, , ast]) => {
        const origin = toOrigin(value);
        return origin === null
          ? ParseResult.fail(
              new ParseResult.Type(
                ast,
                value,
                `Expected a MoltZap server base URL (scheme and host, no path), got ${JSON.stringify(value)}`,
              ),
            )
          : ParseResult.succeed(origin);
      },
      encode: ParseResult.succeed,
    },
  ).pipe(
    Schema.annotations({ description: "Path-free MoltZap server base URL" }),
  )

Decodes either address a caller is likely to hold — the base URL or the socket endpoint — into the path-free base. Any other path fails.

serverUrlTypeCanaries

Variable

export const serverUrlTypeCanaries:

Retains both the runtime positive control and compile-time negative proof.

webSocketUrl

Function

export const webSocketUrl = (base: ServerBaseUrl): string

The socket endpoint a client dials for the given server.

Returns: The web socket url result.

Files

• connect.ts
• index.ts
• server-url.ts
• server-url.types-check.ts