moss
Public
Pull mirror status: ok
S
fix(mesh): stop repeated idle discovery amplification (#28)
.github
cmd
deploy
docs
examples
internal
scripts
site
.dockerignore
.gitignore
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
fly.toml
go.mod
go.sum
LICENSE
Makefile
moss.go
package-lock.json
package.json
postcss.config.js
README.md
SECURITY.md
tailwind.config.js
vite.config.mjs

Moss

Moss is an embeddable P2P mesh core written in Go and exported through CGO as a C-shared library. This repository is the runtime layer, not the end-user chat application.

The current implementation follows the public technical specification in docs/SPECIFICATION.md with a pragmatic v1 runtime:

  • tracker-based bootstrapping via BEP 15 UDP and BEP 3 HTTP announces
  • encrypted peer transport with Noise XX (25519_ChaChaPoly_BLAKE2s) plus identity binding
  • topic-based pub/sub routing with GRAFT/PRUNE control messages, BLAKE2s message IDs, and peer scoring
  • NAT profiling, relay rate limiting primitives, and supernode eligibility checks
  • C FFI surface with examples for C, C++, C#, Python (ctypes), and Rust
  • unit, integration, and shared-library smoke tests

Desktop clients now live in the separate MOSH repository, which consumes MOSS through the shared runtime and a Git submodule pin for compatibility.

Repository role

  • MOSS = runtime, protocol, NAT/relay logic, FFI, examples
  • MOSH = desktop chat client built on top of MOSS

FFI docs:

Repository policy:

Layout

cmd/moss-ffi/              CGO shared library entrypoint
internal/bootstrap/        tracker clients and infohash generation
internal/transport/        encrypted sessions and handshake
internal/gossip/           pubsub cache, scoring, envelopes
internal/nat/              NAT profiling and relay primitives
internal/mesh/             runtime node orchestration
examples/                  C, C++, C#, Python, Python chat, Rust FFI examples

Build

# Linux
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 \
  go build -buildmode=c-shared -o libmoss.so ./cmd/moss-ffi

# Windows
CGO_ENABLED=1 GOOS=windows GOARCH=amd64 \
  go build -buildmode=c-shared -o moss.dll ./cmd/moss-ffi

# macOS
CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 \
  go build -buildmode=c-shared -o libmoss.dylib ./cmd/moss-ffi

The generated header is emitted next to the shared library as moss.h or libmoss.h, depending on the output name.

Quick Start

Build the shared runtime:

go build -buildmode=c-shared -o moss.dll ./cmd/moss-ffi

Then integrate it from your host application through the FFI surface described in:

GitHub Actions publishes release artifacts only from tags.

Main release tags (v*) publish separate shared-library artifacts for both macOS architectures:

  • moss-macos-amd64-shared
  • moss-macos-arm64-shared

Regular main / dev branch CI now runs tests and smoke builds only. It does not upload release artifacts on every push.

Test

go test ./...

If your environment blocks the default Go cache location, set workspace-local cache paths:

GOCACHE=$PWD/.gocache GOTMPDIR=$PWD/.gotmp go test ./...

FFI API

Current exported functions:

  • Moss_Init
  • Moss_Start
  • Moss_Stop
  • Moss_Subscribe
  • Moss_Connect
  • Moss_Unsubscribe
  • Moss_Publish
  • Moss_SetCallback
  • Moss_SetEventCallback
  • Moss_SetScoringCallback
  • Moss_SetKeyStore
  • Moss_GetMeshInfo
  • Moss_GetNetworkStats
  • Moss_GetPublicKey
  • Moss_GetNATType
  • Moss_Free

See docs/API.md for signatures, config fields, event IDs, and error codes.

Web frontend & telemetry

site/ is the static site (landing page, MossScope, and mosh-web), built with Tailwind and deployed to GitHub Pages (see .github/workflows/pages.yml). The same bundle is embedded into moss-scope, so the interface is served both from the site and by any node that opens its debug plane.

make site      # build Tailwind CSS + both wasm bundles into ./site
# serve locally:
python -m http.server 8095 --directory site

Supporting commands:

  • cmd/moss-scope — MossScope: the network explorer and the node debugger in one binary with the web interface embedded (make scope). serve publishes aggregate telemetry and the interface; attach and run open a loopback-only debug session over a token-guarded WebSocket. Deployed at scope.moss.surf.
  • cmd/moss-gateway — the API-only predecessor of moss-scope serve, kept for existing deployments (make gateway).
  • cmd/moss-signal — WebRTC signaling relay for browser peers (make signal).
  • cmd/moss-wasm — browser telemetry verifier; cmd/moss-node-wasm — full peer in wasm.

Telemetry is opt-in (telemetry.enabled), privacy-preserving (HyperLogLog node count, DP-noised bandwidth, unlinkable per-epoch ids), and self-verifying via a BLAKE2s hash chain. See docs/API.md.

Stability Notes

  • The repository is public-ready as a runtime/core project.
  • NAT traversal and relay fallback are implemented and tested, but network behavior still depends on real-world topology.
  • Public client-facing UX issues should go to MOSH.

Local integration example

Two nodes on localhost can be started with one node configured as a static peer of the other:

{
  "trackers": [],
  "static_peers": ["127.0.0.1:41001"],
  "listen_port": 41002
}

The second node connects automatically, exchanges subscriptions, and forwards published messages over the encrypted session.