mirror of
https://github.com/EasyTier/EasyTier.git
synced 2026-10-09 03:27:13 -08:00
KKRainbow
f26c2aa147
* fix(core): normalize secure keys for TOML instances
* feat(wasi): run core behind Cloudflare WebSockets
Introduce the Cloudflare Worker WASI host that runs the EasyTier core
behind host-upgraded WebSockets.
- Worker package scaffold (wrangler Durable Object, build-wasm script,
vitest config) and core-runtime/websocket-host/data-plane runtime.
- WASI host WebSocket tunnel ABI (imports, adapter, runtime exports)
with bounded receive memory and bounded admission queue.
- Route host sockets through the portable listener plan
(HostListenerRegistration, listener queue, admission handler split).
- Build the WASM guest with the aes-gcm feature so secure peer
sessions have their cipher available.
* feat(wasi): add outbound browser client runtime
Add the outbound-only WASI runtime and browser connector host so
browser pages can dial EasyTier peers through WebSocket relays.
- CoreConnectivityMode::{OutboundOnly, InboundOnly} gating for
listeners, discovery, and direct connectivity modules.
- ExternalTunnelConnector plumbing through composite/connector_host/
manual for browser WebSocket dials.
- Browser/Node smoke entries with shared helpers
(smoke-shared.ts).
* feat(wasi): extend browser data plane with TCP half-close
Add the data-plane pieces the browser runtime needs for full-duplex
TCP streams behind host WebSockets:
- Guest TCP shutdown_write operation with submit/take ABI pair
(DATA_PLANE_ABI_VERSION 3 -> 4) and smoltcp half-close support.
- Worker data-plane TCP listener/stream plumbing and core-runtime
listener registration.
- Unit coverage for the new session ops and listener wiring.
* refactor(wasi): make host tunnel ABI transport-neutral
Replace WebSocket-specific core and WASI boundaries with a
message-oriented Host Tunnel interface. Keep WebSocket framing and text
rejection in the Cloudflare host while preserving payload boundaries,
ownership, cancellation, backpressure, and EOF behavior.
Rename feature flags and guest imports and exports to the Host Tunnel
ABI. Update both Worker profiles, tests, and architecture documentation.
* feat(web): split WASI hosts into publishable npm packages
Extract the shared JSPI, WASI, Host Tunnel, and data-plane runtime
into @easytier/runtime. Keep ABI handles, guest memory, TOML, and
operation broker details behind its adapter entry point.
Add typed, auto-starting @easytier/browser and factory-based
@easytier/cloudflare packages. Ship a matching Wasm profile with
each platform package and validate its capabilities before packing.
Persist Cloudflare instance identity in Durable Object storage,
centralize WebSocket admission ownership, and add package-level
coverage for the public interfaces.
* fix(web): make public packages portable
Embed the browser Wasm artifact in the published JavaScript entry
point. This lets esbuild consumers bundle the package without an asset
loader or a copied file.
Return Cloudflare's nominal Durable Object base type and document the
named subclass export required by generated Wrangler bindings.
* docs(web): add public package walkthrough
Expand both package READMEs with installation, configuration, local
validation, health checks, and deployment instructions.
Add a standalone Vite and Wrangler example that imports only the
public Browser and Cloudflare entries. Generate Worker bindings from
configuration and keep local secrets outside version control.
* chore(go): import EasyTier Go host
Add the standalone Go host runtime as a monorepo subtree without
carrying its development branch ancestry.
Preserve its API, tests, examples, generated protobuf bindings, and
embedded WASI artifacts.
* refactor(hosts): colocate Go and JavaScript runtimes
Move the browser, Cloudflare, shared runtime, and web example into
the easytier-js subtree. Update workspace metadata, build paths, and
documentation for the new layout.
Adopt github.com/EasyTier/EasyTier/easytier-go as the Go module path.
Resolve artifact and protobuf generation from the enclosing monorepo.
* build(web): isolate JavaScript host workspace
Keep public browser and Cloudflare packages outside the legacy frontend
workspace so root installs and cross-platform builds do not pull workerd.
Make each package build generate its required WASI artifact from a clean
checkout. Add a dedicated workflow that runs the same install and check
commands documented for contributors.
Move JavaScript dependencies into a scoped lockfile and restore the root
workspace lockfile to its pre-host state.
106 lines
5.3 KiB
Markdown
106 lines
5.3 KiB
Markdown
# EasyTier Domain Context
|
|
|
|
## Module layers
|
|
|
|
`easytier-core` layers dependencies from `foundation` upward through the
|
|
portable networking domains. `foundation` contains infrastructure Modules
|
|
that have no dependency on a networking domain and may be used by any higher
|
|
layer.
|
|
|
|
## Operation broker
|
|
|
|
An operation broker owns the lifecycle of asynchronous work submitted by an
|
|
external caller to core. It allocates opaque operation IDs, arbitrates
|
|
completion, cancellation, and disposal, retains terminal outcomes, and
|
|
publishes a batch-drainable completion queue.
|
|
|
|
The broker does not interpret operation kinds, outcomes, resources, wire
|
|
formats, or domain errors. Each domain Module owns those semantics and composes
|
|
the broker under the same lock as any state that must change atomically with an
|
|
operation transition.
|
|
|
|
Host capability operations use a separate seam. They turn Host readiness into
|
|
Rust task wakeups and do not share the caller-to-core broker state machine.
|
|
|
|
## Credential grant
|
|
|
|
A credential grant contains the authorization constraints shared by generated,
|
|
imported, managed, and attached-peer credentials: ACL groups, relay permission,
|
|
allowed proxy CIDRs, and whether concurrent reuse is allowed. It does not own
|
|
credential identity, key material, lifetime, persistence, or runtime ownership.
|
|
Each credential intake path normalizes the grant before installing it.
|
|
|
|
## Peer Relay advertisement
|
|
|
|
A platform peer may prefer an eligible directly connected credential relay by
|
|
omitting covered credential-leaf edges from only its own advertised OSPF
|
|
connection row. Its local route calculation still uses the complete physical
|
|
adjacency so direct-destination fallback remains available. Other peers'
|
|
source-owned rows and versions are never rewritten, cached for promotion, or
|
|
otherwise changed by this projection.
|
|
|
|
Before a graceful Instance stop, the owner publishes a new-version empty
|
|
connection row while keeping its physical adjacencies available for route
|
|
synchronization. It waits for the current direct route Sessions to acknowledge
|
|
that withdrawal up to a bounded deadline, then continues shutdown. Abrupt
|
|
process loss cannot publish this withdrawal and retains the normal route
|
|
expiry behavior.
|
|
|
|
Relay eligibility comes from the transport-authenticated credential identity
|
|
and grant, not self-reported route metadata. The advertisement Module does not
|
|
support changing a credential's relay permission in place; such a permission
|
|
change is a credential revocation and new authenticated Session.
|
|
|
|
## Attached peer
|
|
|
|
An attached peer is an ordinary `PeerManagerCore` connected to another
|
|
`PeerManagerCore` through an authenticated in-process transport. Each
|
|
authenticated portal client owns one complete peer manager. The managers are
|
|
protocol peers; `attached` describes only the local transport and its trusted
|
|
ingress provenance, not a parent/child peer role.
|
|
|
|
An attached peer owns one complete IPv4 CIDR (for example `10.144.0.5/16`).
|
|
Its address and advertised network are independent of the network manager's
|
|
own static or DHCP address. A VPN portal derives the attached peer route and
|
|
the external client's allowed network from that single CIDR; it does not infer
|
|
either value from the portal-hosting instance.
|
|
|
|
An external portal client uses that same IPv4 address on its native tunnel
|
|
interface. The portal validates the source address and forwards IPv4 packets
|
|
unchanged between the native tunnel and the attached peer; it does not assign
|
|
a second tunnel-only address or perform address translation.
|
|
|
|
Each manager owns its ACL execution state, route service, RPC endpoint, secure
|
|
sessions, packet processing, and lifecycle. Portal code supplies raw packets
|
|
and peer configuration but does not build, reload, or coordinate ACL filters.
|
|
|
|
When the network manager uses Secure Mode, an attached peer authenticates as a
|
|
credential peer. Its portal-owned, in-memory credential grant carries ACL
|
|
groups and is revoked with the attached runtime; the peer never receives the
|
|
network secret or ACL group secrets. A non-Secure-Mode network retains the
|
|
legacy admin-attached identity for compatibility. A credential peer cannot host
|
|
a portal because it cannot issue credential grants. Each live portal Session
|
|
owns a fresh attached-peer identity, while the external client key remains
|
|
stable across Sessions; a replacement Session must never reuse the previous
|
|
non-reusable credential identity.
|
|
|
|
## Compact compatibility Host
|
|
|
|
A compact compatibility Host retains accepted values in the authoritative TOML
|
|
model for management readback, while the shared host-aware normalization path
|
|
omits capabilities that the compact runtime cannot execute. Omitted settings
|
|
are silent no-ops and must not be advertised as live network capabilities.
|
|
|
|
## Web compatibility Host
|
|
|
|
The Web compatibility Host runs the portable EasyTier guest in JavaScript
|
|
runtimes that provide WebAssembly JSPI. Its shared runtime Module owns guest
|
|
lifecycle, Host capability operations, data-plane resources, and WebSocket
|
|
message handling. Browser and Cloudflare Adapters own only the platform-specific
|
|
way that WebSockets are dialed or accepted and the matching guest artifact.
|
|
|
|
The Browser Adapter is an outbound-only EasyTier instance with a smoltcp TCP
|
|
data plane. The Cloudflare Adapter is an inbound-only relay hosted by one named
|
|
Durable Object. Their public configuration exposes only capabilities each Host
|
|
can execute; guest ABI details and serialized TOML remain internal.
|