Hypha Mesh

The communication layer of Hypha version 2

sourceASD-STE100 Simplified Technical English

Hypha Mesh connects programs to each other across the Cloudflare edge. Each program can supply a service, and each program can call the services of the others. This page is a standalone document, so it carries its own way back: hypha.run · under the hood · production readiness.

A

What it is

The core idea

One workspace is one Durable Object at the edge. All the clients of that workspace connect to it. Any client can supply a service. Any client can call a service.

A client is a browser page, a command-line tool, or a daemon on a user machine. The mesh is a transport layer with a thin control plane. It is not a general remote-object system. It is deliberately small.

B

The anchor

socket + tokensocket + tokensocket + tokenroute by nameservices, presenceartifact bytesBrowserWorkerCLIDaemonWorkspace DOSQLR2

Cloudflare keeps one copy of the Durable Object in the world. Therefore it is the single source of truth.

C

The six primitives

# Primitive What it does
1 Auth and scope The Worker checks a passcode or a JWT. It then finds the workspace and the user.
2 Register and discover A client registers a named service. The other clients find it.
3 Presence The mesh reports PRESENT or ABSENT for each service.
4 Unary call One call to one method. One reply.
5 Subscription The server sends an ordered stream of events to the client.
6 Backpressure A slow receiver decreases the speed of a stream.

There are no other primitives. Calls go from the caller to the service. Streams go from the server to the client.

D

Presence

A service is PRESENT when its socket is open and its heartbeat is recent. A service is ABSENT when one of the two facts is false. Only the Durable Object decides presence, because only it sees all the connections. A client can read presence one time. A client can also subscribe to the changes.

E

How a call moves

Client ADOClient Bregister_service1get_service2service handle3call a method4call a method5result6result7No direct path. The DO is the onlycommon point.
F

The objects above

  • Doca value that stays equal on all the clients
  • Logan append stream; a new subscriber reads the history first
  • Artifactfiles; the DO keeps the index, R2 keeps the bytes
  • Tunnela public address for a machine that has none

These four objects use the six primitives. They are not new primitives.

G

What it is not

Feature In the mesh Why
The hypha-rpc wire protocol The API has the same shape, but the bytes differ. A hypha-rpc client cannot connect.
Callback functions across the network They caused the dead-reference faults in version 1.
Nested object proxies The mesh drops them on purpose, to keep the protocol small.
Generators Use a topic subscription in place of them.
Calls between two clients The Durable Object routes them.
Hibernation of an idle workspace The sockets stay open. The cost stays low.
How to move an application

Read docs/HYPHA-RPC-MIGRATION.md. Change callbacks to server streams. Change interface proxies to named services. Change generators to topic subscriptions.