driver

package
v0.5.7 Latest Latest
Warning

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

 Go to latest Published: Jul 3, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultSocketPath 

func DefaultSocketPath() string

DefaultSocketPath returns the default Unix socket path for IPC. On Linux it prefers $XDG_RUNTIME_DIR (typically /run/user/<uid>, which is private to the user); falls back to /tmp/pilot.sock. On macOS /tmp is already per-user via SIP, so /tmp/pilot.sock is safe.

Types

type Conn 

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

Conn implements net.Conn over a Pilot Protocol stream.

Concurrency: like *net.TCPConn, a Conn may be used by at most one reader and one writer goroutine at a time. Read serialises concurrent callers with readMu (so recvBuf is never corrupted), but interleaving two readers still yields each a non-deterministic slice of the stream; do not do that. Write is safe for one writer; concurrent writers may interleave chunks on the wire. SetDeadline/SetReadDeadline/ SetWriteDeadline are safe to call from any goroutine.

func (*Conn) Close 

func (c *Conn) Close() error

func (*Conn) LocalAddr 

func (c *Conn) LocalAddr() net.Addr

func (*Conn) Read 

func (c *Conn) Read(b []byte) (int, error)

func (*Conn) RemoteAddr 

func (c *Conn) RemoteAddr() net.Addr

func (*Conn) SetDeadline 

func (c *Conn) SetDeadline(t time.Time) error

func (*Conn) SetReadDeadline 

func (c *Conn) SetReadDeadline(t time.Time) error

func (*Conn) SetWriteDeadline 

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets a deadline for Write. A passed deadline causes Write to return os.ErrDeadlineExceeded. Because Write never blocks waiting on a remote peer (it only enqueues chunks to the local daemon over IPC), the deadline is enforced before each chunk rather than via an interrupt — a zero time clears it. This satisfies the net.Conn contract instead of the previous silent no-op.

func (*Conn) Write 

func (c *Conn) Write(b []byte) (int, error)

Write enqueues b to the local daemon over IPC, splitting it into maxSendChunk-sized cmdSend frames.

Send semantics: a nil error and n == len(b) mean every chunk was handed to the local daemon over IPC — NOT that the bytes were transmitted on the wire or acknowledged by the peer. The Pilot stream layer in the daemon handles retransmission/ordering after this point; Write does not block on it. Errors reported here are local IPC write failures or a passed write deadline.

type Datagram 

type Datagram struct {
	SrcAddr protocol.Addr
	SrcPort uint16
	DstPort uint16
	Data    []byte
}

Datagram represents a received unreliable datagram.

type Driver 

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

Driver is the main entry point for the Pilot Protocol SDK.

func Connect 

func Connect(socketPath string) (*Driver, error)

Connect creates a new driver connected to the local daemon.

func (*Driver) ApproveHandshake 

func (d *Driver) ApproveHandshake(nodeID uint32) (map[string]interface{}, error)

ApproveHandshake approves a pending trust handshake request.

func (*Driver) Broadcast 

func (d *Driver) Broadcast(netID uint16, port uint16, data []byte, adminToken string) error

Broadcast fans an unreliable datagram out to every member of a network. The admin token must match the daemon's configured Config.AdminToken; an empty token or mismatched token is rejected. Permitted on every network including network 0 (backbone). Sender membership is not required.

func (*Driver) Close 

func (d *Driver) Close() error

Close disconnects from the daemon.

func (*Driver) Deregister 

func (d *Driver) Deregister() (map[string]interface{}, error)

Deregister removes the daemon from the registry.

func (*Driver) Dial 

func (d *Driver) Dial(addr string) (*Conn, error)

Dial opens a stream connection to a remote address:port. addr format: "N:XXXX.YYYY.YYYY:PORT"

func (*Driver) DialAddr 

func (d *Driver) DialAddr(dst protocol.Addr, port uint16) (*Conn, error)

DialAddr opens a stream connection to a remote Addr + port. It applies defaultDialTimeout so a non-responsive daemon cannot block the caller indefinitely; use DialAddrTimeout to supply an explicit bound.

func (*Driver) DialAddrTimeout 

func (d *Driver) DialAddrTimeout(dst protocol.Addr, port uint16, timeout time.Duration) (*Conn, error)

DialAddrTimeout opens a stream connection with a client-side timeout. If the daemon does not respond within the timeout, the dial is cancelled.

func (*Driver) Disconnect 

func (d *Driver) Disconnect(connID uint32) error

Disconnect closes a connection by ID. Used by administrative tools. Fire-and-forget: the daemon always responds CmdCloseOK regardless of whether the connID exists, so there is no error to propagate. Using sendAndWait here would corrupt a concurrent sendAndWait for a different command if a server-pushed cmdCloseOK (remote FIN) arrived simultaneously.

func (*Driver) EnrollRecovery added in v0.5.2 

func (d *Driver) EnrollRecovery(enrollment, enrollmentSig string) (map[string]interface{}, error)

EnrollRecovery records this node's opaque recovery commitment so the address can later be recovered if the current key is lost. enrollment and enrollmentSig come from the verifier sidecar; the daemon signs proof of the current key over the commitment before forwarding to the registry. The raw external identity never leaves the verifier — only the commitment.

func (*Driver) Handshake 

func (d *Driver) Handshake(nodeID uint32, justification string) (map[string]interface{}, error)

Handshake sends a trust handshake request to a remote node.

func (*Driver) Health 

func (d *Driver) Health() (map[string]interface{}, error)

Health returns a lightweight health check from the daemon.

func (*Driver) Info 

func (d *Driver) Info() (map[string]interface{}, error)

Info returns the daemon's status information.

func (*Driver) Listen 

func (d *Driver) Listen(port uint16) (*Listener, error)

Listen binds a port and returns a Listener that accepts connections.

func (*Driver) ManagedForceCycle 

func (d *Driver) ManagedForceCycle(networkID uint16) (map[string]interface{}, error)

ManagedForceCycle forces a prune/fill cycle in a managed network.

func (*Driver) ManagedReconcile 

func (d *Driver) ManagedReconcile(networkID uint16) (map[string]interface{}, error)

ManagedReconcile asks the daemon's policy runner for networkID to poll the registry and refresh its peer set — without running a policy cycle. Returns {network_id, peers}.

func (*Driver) ManagedStatus 

func (d *Driver) ManagedStatus(networkID uint16) (map[string]interface{}, error)

ManagedStatus returns the status of a managed network engine.

func (*Driver) MemberTagsGet 

func (d *Driver) MemberTagsGet(networkID uint16, nodeID uint32) (map[string]interface{}, error)

MemberTagsGet retrieves admin-assigned member tags for a node in a network.

func (*Driver) MemberTagsSet 

func (d *Driver) MemberTagsSet(networkID uint16, nodeID uint32, tags []string) (map[string]interface{}, error)

MemberTagsSet sets admin-assigned member tags for a node in a network.

func (*Driver) NetworkInvite 

func (d *Driver) NetworkInvite(networkID uint16, targetNodeID uint32) (map[string]interface{}, error)

NetworkInvite invites a target node to a network (requires admin token on daemon).

func (*Driver) NetworkJoin 

func (d *Driver) NetworkJoin(networkID uint16, token string) (map[string]interface{}, error)

NetworkJoin joins a network by ID, optionally using a token for token-gated networks.

func (*Driver) NetworkLeave 

func (d *Driver) NetworkLeave(networkID uint16) (map[string]interface{}, error)

NetworkLeave leaves a network by ID.

func (*Driver) NetworkList 

func (d *Driver) NetworkList() (map[string]interface{}, error)

NetworkList returns all networks known to the registry.

func (*Driver) NetworkMembers 

func (d *Driver) NetworkMembers(networkID uint16) (map[string]interface{}, error)

NetworkMembers lists all members of a network.

func (*Driver) NetworkPollInvites 

func (d *Driver) NetworkPollInvites() (map[string]interface{}, error)

NetworkPollInvites returns pending network invites for this node.

func (*Driver) NetworkRespondInvite 

func (d *Driver) NetworkRespondInvite(networkID uint16, accept bool) (map[string]interface{}, error)

NetworkRespondInvite accepts or rejects a pending network invite.

func (*Driver) PendingHandshakes 

func (d *Driver) PendingHandshakes() (map[string]interface{}, error)

PendingHandshakes returns pending trust handshake requests.

func (*Driver) PolicyGet 

func (d *Driver) PolicyGet(networkID uint16) (map[string]interface{}, error)

PolicyGet retrieves the active policy for a network from the daemon.

func (*Driver) PolicySet 

func (d *Driver) PolicySet(networkID uint16, policyJSON []byte, adminToken string) (map[string]interface{}, error)

PolicySet sends a policy document to the daemon for immediate application. adminToken authenticates the caller as a network administrator — pilot-daemon's managed.policy.set IPC handler validates this against its configured AdminToken before applying the policy. Empty token is accepted by the daemon iff it has no AdminToken configured (default solo-mode daemons); managed-mode daemons reject empty tokens. (PILOT-233)

func (*Driver) PreferDirect added in v0.5.0 

func (d *Driver) PreferDirect(nodeID uint32) (map[string]interface{}, error)

PreferDirect asks the daemon to drop the existing tunnel to the peer and any sticky routing state (cached endpoint, cached resolve, unpinned relay flag), then re-resolve from the registry and prefer a direct UDP path on the next dial. Returns the new routing state the daemon arrived at — typically {"node_id": N, "relay_active": false, "pinned": false, "real_addr": "..."} when a direct path was found, or relay_active=true when the registry's relay_only flag is authoritative or the punch failed.

Useful when stream traffic (pilotctl send-file) is failing on a relay path while small UDP (pilotctl ping) still works — typical symptom of a beacon-mediated tunnel that established once and then stuck.

Backward compatibility: an old daemon (no CmdPreferDirect) returns an "unknown command" error — callers should treat that as "best-effort hint" and proceed with the normal dial, not abort the operation.

func (*Driver) RecvFrom 

func (d *Driver) RecvFrom() (*Datagram, error)

RecvFrom receives the next incoming datagram.

func (*Driver) RejectHandshake 

func (d *Driver) RejectHandshake(nodeID uint32, reason string) (map[string]interface{}, error)

RejectHandshake rejects a pending trust handshake request.

func (*Driver) ResolveHostname 

func (d *Driver) ResolveHostname(hostname string) (map[string]interface{}, error)

ResolveHostname resolves a hostname to node info via the daemon.

func (*Driver) RevokeTrust 

func (d *Driver) RevokeTrust(nodeID uint32) (map[string]interface{}, error)

RevokeTrust removes a peer from the trusted set and notifies the registry.

func (*Driver) RotateKey 

func (d *Driver) RotateKey() (map[string]interface{}, error)

RotateKey asks the daemon to rotate its Ed25519 identity at the registry. The daemon generates a new keypair, signs proof of the current key, calls registry.RotateKey, then atomically swaps and persists the new identity.

func (*Driver) SendTo 

func (d *Driver) SendTo(dst protocol.Addr, port uint16, data []byte) error

SendTo sends an unreliable unicast datagram to the given address:port. Broadcast addresses (Node=0xFFFFFFFF) are not accepted on this path; use Broadcast, which requires the daemon's admin token.

Send semantics: this is fire-and-forget. A nil return means only that the frame was successfully enqueued to the local daemon over IPC — it does NOT indicate the datagram was transmitted on the wire, routed, or delivered to the peer. Datagrams are unreliable; there is no acknowledgement. The only errors reported are local IPC failures (empty/oversized frame, socket write error).

func (*Driver) SetHostname 

func (d *Driver) SetHostname(hostname string) (map[string]interface{}, error)

SetHostname sets or clears the daemon's hostname via the registry.

func (*Driver) SetTags 

func (d *Driver) SetTags(tags []string) (map[string]interface{}, error)

SetTags sets the capability tags for this daemon's node.

func (*Driver) SetVisibility 

func (d *Driver) SetVisibility(public bool) (map[string]interface{}, error)

SetVisibility sets the daemon's visibility on the registry.

func (*Driver) SetWebhook 

func (d *Driver) SetWebhook(url string) (map[string]interface{}, error)

SetWebhook sets or clears the daemon's webhook URL at runtime. An empty URL disables the webhook.

func (*Driver) SignEnvelope added in v0.5.7 

func (d *Driver) SignEnvelope(audience, bodyHash string) (map[string]interface{}, error)

SignEnvelope asks the daemon to sign a request-signature envelope (common/reqsig) for the given audience over the given body hash (64 lowercase hex chars — sha256 of the request body, see reqsig.HashBody). The daemon constructs the envelope itself — its own address, the current timestamp, a fresh nonce — and signs only the reqsig canonical form; it never signs caller-supplied raw strings. Returns {envelope, signature, address}.

func (*Driver) SubmitBadge added in v0.5.2 

func (d *Driver) SubmitBadge(badge, badgeSig string) (map[string]interface{}, error)

SubmitBadge attaches a verified-address badge to this node's registry entry. badge and badgeSig are produced out-of-band by the verifier sidecar; the daemon signs proof of the current key over the badge before forwarding to the registry, which also verifies the badge offline against the pinned issuer key. Verification is optional — nodes without a badge keep working unchanged.

func (*Driver) TrustedPeers 

func (d *Driver) TrustedPeers() (map[string]interface{}, error)

TrustedPeers returns all trusted peers from the handshake protocol.

func (*Driver) VerifyEnvelope added in v0.5.7 

func (d *Driver) VerifyEnvelope(envelope, sigB64 string, checkStanding bool) (map[string]interface{}, error)

VerifyEnvelope checks a canonical reqsig envelope + base64 signature via the daemon, which resolves the claimed node's key from its local cache first and the registry on miss. With checkStanding the daemon also reports the signer's registry standing (online, last_seen_unix, key_generation, network_member) when the registry provides it. A failed check is NOT an error — the reply carries valid=false plus a reason.

func (*Driver) VerifyEnvelopeMaxSkew added in v0.5.7 

func (d *Driver) VerifyEnvelopeMaxSkew(envelope, sigB64 string, checkStanding bool, maxSkewSecs uint32) (map[string]interface{}, error)

VerifyEnvelopeMaxSkew is VerifyEnvelope with an explicit freshness window in seconds. 0 selects the daemon default (reqsig.DefaultMaxSkew).

func (*Driver) WaitForTrust 

func (d *Driver) WaitForTrust(nodeID uint32, timeoutMs uint32) (map[string]interface{}, error)

WaitForTrust blocks (in the daemon) until the peer transitions to trusted or the timeout elapses. Single IPC roundtrip — the daemon-side HandshakeService.WaitForTrust waits on a per-node channel that is closed the moment trust is granted, so wakeup latency is sub-millisecond.

Backward compatibility: an old daemon (no SubHandshakeWait) returns an "unknown sub-command" error; callers should treat that as "wait skipped" and proceed.

type Listener 

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

Listener implements net.Listener over a Pilot Protocol port.

func (*Listener) Accept 

func (l *Listener) Accept() (net.Conn, error)

func (*Listener) Addr 

func (l *Listener) Addr() net.Addr

func (*Listener) Close 

func (l *Listener) Close() error

Source Files

View all Source files

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.