api

Documentation

Overview

Package api serves the node's HTTP REST surface (Gin) under /api/v2. It replaces the v1 api/v1 tree and the deleted gRPC server. Provisioning logic lives in the Provisioner so Phase 2 can extend it with sing-box credentials without touching the handlers.

Index

• Constants
• type CredentialBundle
• type EndpointsStatus
• type Identity
• type IdentityStatus
• type NodeStats
• type PeerInfo
• type PeerRequest
• type Provisioner
• type Server
  • func NewServer(cfg *config.Config, prov Provisioner, id Identity) *Server
  • func (s *Server) Router() *gin.Engine
  • func (s *Server) SetDropService(service *drop.Service)
  • func (s *Server) SetReadinessProvider(fn func() readiness.Input)
  • func (s *Server) SetServiceSnapshot(fn func() map[string]string)
  • func (s *Server) SetStatus(status string)
  • func (s *Server) SetWireGuardPublicKeyProvider(fn func() string)
• type StatusResponse
• type TransportEntry
• type WireGuardBundle
• type WireGuardEndpointStatus

Constants

const BundleVersion = 2

Types

type CredentialBundle

type CredentialBundle struct {
	BundleVersion    int              `json:"bundle_version"`
	NodeID           string           `json:"node_id,omitempty"`
	ID               string           `json:"id"`
	IssuedAt         int64            `json:"issued_at"`
	ExpiresAt        int64            `json:"expires_at,omitempty"`
	WireGuard        WireGuardBundle  `json:"wireguard"`
	Transports       []TransportEntry `json:"transports,omitempty"`
	VLESSURI         string           `json:"vless_uri,omitempty"`
	Hysteria2URI     string           `json:"hysteria2_uri,omitempty"`
	SingboxProfile   any              `json:"singbox_profile,omitempty"`
	ServiceDiscovery map[string]any   `json:"service_discovery,omitempty"`
}

CredentialBundle is the unified response for peer provisioning and re-fetch.

type EndpointsStatus

type EndpointsStatus struct {
	WireGuard WireGuardEndpointStatus `json:"wireguard"`
}

EndpointsStatus mirrors the gateway discovery projection for this node.

type Identity

type Identity struct {
	PeerID string
	DID    string
}

Identity supplies the node's stable identifiers for the status endpoint.

type IdentityStatus

type IdentityStatus struct {
	Configured    bool   `json:"configured"`
	PeerID        string `json:"peer_id"`
	DID           string `json:"did"`
	WalletChain   string `json:"wallet_chain,omitempty"`
	WalletLabel   string `json:"wallet_chain_label,omitempty"`
	WalletAddress string `json:"wallet_address,omitempty"`
}

IdentityStatus summarizes the node's cryptographic identity (never includes secrets).

type NodeStats

type NodeStats struct {
	Status         string   `json:"status"`
	Version        string   `json:"version"`
	Region         string   `json:"region"`
	Zone           string   `json:"zone,omitempty"`
	Protocols      []string `json:"protocols"`
	TotalPeers     int      `json:"total_peers"`     // provisioned in the store
	ConnectedPeers int      `json:"connected_peers"` // handshake in the last 3m
	RxBytes        int64    `json:"rx_bytes"`        // cumulative since interface up
	TxBytes        int64    `json:"tx_bytes"`
	UptimeSec      int64    `json:"uptime_sec"`
}

NodeStats is the coarse, public operational snapshot powering the local dashboard. It deliberately exposes only aggregates — never per-client data.

type PeerInfo

type PeerInfo struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	WGAllowedIP string `json:"wg_allowed_ip"`
	Enabled     bool   `json:"enabled"`
	CreatedAt   int64  `json:"created_at"`
	ExpiresAt   int64  `json:"expires_at"`
}

PeerInfo is the metadata-only listing item (no credentials).

type PeerRequest

type PeerRequest struct {
	Name           string `json:"name"`
	Wallet         string `json:"wallet"`
	WGPublicKey    string `json:"wg_public_key"`
	WGPresharedKey string `json:"wg_preshared_key"`
	ExpiresAt      int64  `json:"expires_at"`
}

PeerRequest is the body of PUT /api/v2/peers/{id}.

type Provisioner

type Provisioner interface {
	UpsertPeer(ctx context.Context, id string, req PeerRequest) (*CredentialBundle, error)
	DeletePeer(ctx context.Context, id string) error
	Credentials(ctx context.Context, id string) (*CredentialBundle, error)
	ListPeers(ctx context.Context) ([]PeerInfo, error)
	Stats(ctx context.Context) (*NodeStats, error)
}

Provisioner turns a peer request into a stored peer and a credential bundle. Implemented by node.Service; abstracted so handlers stay transport-only.

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server wires the Gin engine.

func NewServer

func NewServer(cfg *config.Config, prov Provisioner, id Identity) *Server

NewServer builds the API server.

func (*Server) Router

func (s *Server) Router() *gin.Engine

Router returns the configured Gin engine.

func (*Server) SetDropService

func (s *Server) SetDropService(service *drop.Service)

SetDropService enables the optional exact-purpose Drop API.

func (*Server) SetReadinessProvider

func (s *Server) SetReadinessProvider(fn func() readiness.Input)

SetReadinessProvider supplies live signals for readiness evaluation.

func (*Server) SetServiceSnapshot

func (s *Server) SetServiceSnapshot(fn func() map[string]string)

SetServiceSnapshot supplies attached service health for /api/v2/status.

func (*Server) SetStatus

func (s *Server) SetStatus(status string)

SetStatus updates the public status field (online | draining).

func (*Server) SetWireGuardPublicKeyProvider

func (s *Server) SetWireGuardPublicKeyProvider(fn func() string)

SetWireGuardPublicKeyProvider supplies the node's WireGuard server public key.

type StatusResponse

type StatusResponse struct {
	Version      string          `json:"version"`
	NodeName     string          `json:"node_name"`
	Region       string          `json:"region"`
	Zone         string          `json:"zone,omitempty"`
	Status       string          `json:"status"`
	AccessMode   string          `json:"access_mode"`
	PeerID       string          `json:"peer_id"` // deprecated: use identity.peer_id
	DID          string          `json:"did"`     // deprecated: use identity.did
	Identity     IdentityStatus  `json:"identity"`
	Endpoints    EndpointsStatus `json:"endpoints"`
	Capabilities map[string]any  `json:"capabilities"`
	Protocols    []string        `json:"protocols"`
	Readiness    any             `json:"readiness"`
}

StatusResponse is the public node status.

type TransportEntry

type TransportEntry struct {
	Kind string `json:"kind"`
	URI  string `json:"uri,omitempty"`
}

TransportEntry describes one carrier in a v2 credential bundle.

type WireGuardBundle

type WireGuardBundle struct {
	ClientConf      string `json:"client_conf"`
	ServerPublicKey string `json:"server_public_key"`
	Endpoint        string `json:"endpoint"`
	Address         string `json:"address"`
	DNS             string `json:"dns"`
}

WireGuardBundle holds everything a client needs for the WireGuard fast path.

type WireGuardEndpointStatus

type WireGuardEndpointStatus struct {
	Port      int    `json:"port"`
	PublicKey string `json:"public_key"`
	Endpoint  string `json:"endpoint"` // host:port clients dial
}

WireGuardEndpointStatus is the node's WireGuard listen endpoint (server key + port).