edgefabric

module
v0.0.0-...-28e1e40 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 13, 2026 License: MIT

README

EdgeFabric

CI Go

A distributed edge networking platform that orchestrates a global fleet of nodes to deliver anycast IP services, authoritative DNS, CDN, and edge-to-private-network routing — all managed from a single control plane.

Features

  • Fleet Management — Register, provision, and monitor edge nodes and gateways with heartbeat tracking and config drift detection
  • WireGuard Mesh — Automatic overlay network between controller, nodes, and gateways with encrypted tunnels and key management
  • BGP Anycast — Announce IP prefixes via BGP from globally distributed nodes for geographic load distribution
  • Authoritative DNS — Centrally managed DNS zones (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR) served from edge nodes
  • CDN — Reverse proxy with caching (memory + disk), TLS termination (auto via ACME / disabled; manual certificate upload planned), gzip + brotli compression, WAF, rate limiting, and origin health checks
  • Route Forwarding — TCP/UDP/ICMP forwarding through gateways into private networks
  • Multi-tenant — Isolated tenants with role-based access control (superuser, admin, readonly) and per-tenant observability
  • Provisioning — SSH-based node enrollment, start/stop/restart/upgrade/decommission lifecycle
  • Authentication — JWT tokens, TOTP two-factor, API keys for programmatic access, rate-limited auth endpoints
  • Audit Logging — Every state-changing operation is recorded
  • Observability — Structured logging, Prometheus metrics (including per-tenant), health/readiness/liveness endpoints
  • High Availability — PostgreSQL backend with leader election; SQLite for single-instance deployments
  • Notifications — Event bus with webhook, Slack, and email notification handlers
  • Plugin System — Extensible plugin registry for service runtimes (BGP, DNS, CDN, Route)
  • Kubernetes Operator — CRDs for managing EdgeFabric resources from Kubernetes
  • Web Console — Embedded React SPA with real-time dashboard, fleet management, DNS/CDN configuration
  • Single Binary — One Go binary runs as controller, node, or gateway (SPA included)

Architecture

┌──────────────┐     WireGuard      ┌──────────┐
│  Controller  │◄──────────────────►│  Node A  │──► BGP, DNS, CDN
│  (API + UI)  │◄──────────┐       └──────────┘
└──────────────┘           │        ┌──────────┐
                           ├───────►│  Node B  │──► BGP, DNS, CDN
                           │        └──────────┘
                           │        ┌──────────┐     ┌─────────────┐
                           └───────►│ Gateway  │────►│ Private Net │
                                    └──────────┘     └─────────────┘

The controller is the central management plane: API server, WireGuard hub, database (SQLite or Postgres). Nodes are edge compute agents that run DNS, CDN, BGP, and route forwarding services. Gateways are traffic entry points that forward inbound connections into private networks.

See ARCHITECTURE.md for the full design.

Quick Start

docker compose up --build

This builds the controller, starts it, and seeds it with a sample tenant, users, nodes, gateways, DNS zones, CDN sites, and routes. See demo/README.md for details.

After setup completes:

# Health check
curl http://localhost:8443/healthz

# Login (password is printed in the demo output)
curl -s -X POST http://localhost:8443/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@edgefabric.local","password":"<password>"}' | jq

Cleanup:

docker compose down -v
Build from Source
# Prerequisites: Go 1.23+, Node.js 20+, Task (https://taskfile.dev)
go install github.com/go-task/task/v3/cmd/task@latest

# Build
task build
./bin/edgefabric version

# Generate encryption key
openssl rand -base64 32

# Create config (see examples/controller.yaml for all options)
cp edgefabric.example.yaml edgefabric.yaml
# Edit edgefabric.yaml: set encryption_key

# Run controller
./bin/edgefabric controller --config edgefabric.yaml

On first boot, the admin password is logged once to stdout.

Subcommands

edgefabric controller   # Run the control plane (API + WireGuard hub)
edgefabric node         # Run an edge node (DNS, CDN, BGP, routing)
edgefabric gateway      # Run a gateway (private network bridge)
edgefabric version      # Print version info

Configuration

Copy edgefabric.example.yaml and edit for your deployment. Detailed, commented configs for each role are in examples/:

All settings support EF_-prefixed environment variable overrides for container deployments.

Documentation

Document Audience Description
API Guide Developers REST API with curl examples for every endpoint
Developer Guide Contributors Clone → test in 10 minutes, code conventions, adding endpoints
Deployment Guide Operators Production install, systemd, Docker, security checklist
Architecture Everyone System design and component overview
Security Model Operators Authentication, RBAC, encryption at rest
Tenancy & RBAC Operators Multi-tenant isolation and role model
Networking Model Operators WireGuard overlay, BGP, IP allocations
Provisioning Model Operators Node enrollment and lifecycle
Domain Model Contributors Entity relationships
Operations Operators Backup, restore, upgrades
OpenAPI Spec Developers Full API specification (3,300+ lines)
Roadmap Everyone Milestone status and future plans
Demo Evaluators Docker Compose demo environment

Project Structure

cmd/edgefabric/           CLI entrypoint (controller, node, gateway subcommands)
internal/
  api/                    HTTP API layer (router, middleware, v1 handlers)
  app/                    Application wiring per role
  domain/                 Domain types (entities, value objects)
  config/                 YAML config + env var overrides
  storage/sqlite/         SQLite persistence (all store interfaces)
  auth/                   JWT, TOTP, API keys, password hashing
  rbac/                   Role-based access control
  tenant/                 Tenant management
  user/                   User management
  fleet/                  Node/gateway/group/SSH key inventory
  provisioning/           SSH-based node enrollment + lifecycle
  networking/             WireGuard, BGP sessions, IP allocations
  dns/                    DNS zone + record management
  cdn/                    CDN site + origin management
  route/                  Route CRUD + gateway config generation
  audit/                  Audit event logging
  events/                 In-process event bus
  observability/          Structured logging, Prometheus, health checks
  secrets/                AES-256 encryption at rest
  ssh/                    SSH client for provisioning
  wireguard/              WireGuard interface management
  ha/                     High availability (leader election)
  plugin/                 Plugin system (extensible service registry)
  bgp/, dnsserver/, cdnserver/, routeserver/, gatewayrt/
                          Node/gateway-side service runtimes
pkg/version/              Build-time version info
web/console/              SPA source (React + TypeScript + Vite)
web/static/               SPA build output (embedded at /)
operator/                 Kubernetes operator (CRDs + reconcilers)
deploy/docker/            Dockerfile (multi-stage alpine build)
deploy/systemd/           Hardened systemd units
demo/                     Docker Compose demo environment
examples/                 Production example configs
docs/                     Documentation
openapi/                  OpenAPI 3.0.3 specification

Development

task check    # lint + vet + test + SPA typecheck (full CI equivalent)
task test     # tests with race detector
task lint     # golangci-lint
task dev      # build and run controller with config.dev.yaml
task dev-spa  # run Vite dev server with hot-reload (proxies to Go backend)

See the Developer Guide for the full setup walkthrough.

License

MIT — see LICENSE.

Directories

Path Synopsis
internal
api
Package api assembles the full HTTP handler for the EdgeFabric controller.
 Package api assembles the full HTTP handler for the EdgeFabric controller.
api/apiutil
Package apiutil provides shared helpers for API handlers.
 Package apiutil provides shared helpers for API handlers.
api/middleware
Package middleware provides HTTP middleware for the EdgeFabric API.
 Package middleware provides HTTP middleware for the EdgeFabric API.
api/v1
Package v1 implements the EdgeFabric REST API v1 handlers.
 Package v1 implements the EdgeFabric REST API v1 handlers.
app
Package app contains the application wiring for each binary mode.
 Package app contains the application wiring for each binary mode.
audit
Package audit provides audit logging for all state-changing operations.
 Package audit provides audit logging for all state-changing operations.
auth
Package auth handles authentication: password, TOTP 2FA, and API keys.
 Package auth handles authentication: password, TOTP 2FA, and API keys.
bgp
Package bgp defines the node-side BGP runtime interface and implementations.
 Package bgp defines the node-side BGP runtime interface and implementations.
cdn
Package cdn implements the controller-side CDN site and origin management service.
 Package cdn implements the controller-side CDN site and origin management service.
cdnserver
Package cdnserver implements the node-side CDN reverse proxy server.
 Package cdnserver implements the node-side CDN reverse proxy server.
config
Package config handles loading and validating EdgeFabric configuration.
 Package config handles loading and validating EdgeFabric configuration.
crypto
Package crypto provides key generation and encryption utilities.
 Package crypto provides key generation and encryption utilities.
dns
Package dns implements the controller-side DNS zone and record management service.
 Package dns implements the controller-side DNS zone and record management service.
dnsserver
Package dnsserver implements the node-side authoritative DNS server.
 Package dnsserver implements the node-side authoritative DNS server.
domain
events
Package events provides an in-process event bus for broadcasting system events to subscribers.
 Package events provides an in-process event bus for broadcasting system events to subscribers.
fleet
Package fleet manages node and gateway inventory and health.
 Package fleet manages node and gateway inventory and health.
gatewayclient
Package gatewayclient provides an HTTP client for gateway agents to poll configuration from the controller.
 Package gatewayclient provides an HTTP client for gateway agents to poll configuration from the controller.
gatewayrt
Package gatewayrt implements the gateway-side route forwarding runtime.
 Package gatewayrt implements the gateway-side route forwarding runtime.
gatewaystate
Package gatewaystate manages the local state file for a gateway agent.
 Package gatewaystate manages the local state file for a gateway agent.
ha
Package ha provides high-availability primitives for EdgeFabric controllers.
 Package ha provides high-availability primitives for EdgeFabric controllers.
networking
nodeclient
Package nodeclient provides an HTTP client for node agents to poll configuration from the controller.
 Package nodeclient provides an HTTP client for node agents to poll configuration from the controller.
nodestate
Package nodestate manages the local state file for a node agent.
 Package nodestate manages the local state file for a node agent.
observability
Package observability provides structured logging, metrics, and health checks.
 Package observability provides structured logging, metrics, and health checks.
plugin
Package plugin provides a typed plugin registry for EdgeFabric services.
 Package plugin provides a typed plugin registry for EdgeFabric services.
provisioning
Package provisioning orchestrates node lifecycle operations.
 Package provisioning orchestrates node lifecycle operations.
rbac
Package rbac implements role-based access control.
 Package rbac implements role-based access control.
route
Package route implements the controller-side route management service.
 Package route implements the controller-side route management service.
routeserver
Package routeserver implements the node-side route forwarding runtime.
 Package routeserver implements the node-side route forwarding runtime.
secrets
Package secrets provides encrypted secret storage using AES-256-GCM.
 Package secrets provides encrypted secret storage using AES-256-GCM.
ssh
Package ssh provides an abstraction for SSH operations used during node provisioning.
 Package ssh provides an abstraction for SSH operations used during node provisioning.
storage
Package storage defines the persistence abstraction for EdgeFabric.
 Package storage defines the persistence abstraction for EdgeFabric.
storage/postgres
Package postgres implements the storage.Store interface using PostgreSQL.
 Package postgres implements the storage.Store interface using PostgreSQL.
storage/sqlite
Package sqlite implements the storage.Store interface using SQLite.
 Package sqlite implements the storage.Store interface using SQLite.
tenant
Package tenant manages tenant lifecycle and isolation.
 Package tenant manages tenant lifecycle and isolation.
user
Package user manages user lifecycle and CRUD operations.
 Package user manages user lifecycle and CRUD operations.
Package openapi provides the embedded OpenAPI specification.
 Package openapi provides the embedded OpenAPI specification.
pkg
version
Package version provides build-time version information.
 Package version provides build-time version information.
Package web provides the embedded static files for the SPA.
 Package web provides the embedded static files for the SPA.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.