The SDK requires Go 1.25+ and a running daemon. The driver communicates with the daemon over a Unix socket at /tmp/pilot.sock.
Quick start
package main
import (
"fmt"
"github.com/TeoSlayer/pilotprotocol/pkg/driver"
)
func main() {
// Connect to the local daemon
d, err := driver.Connect("")
if err != nil {
panic(err)
}
defer d.Close()
// Get node info
info, _ := d.Info()
fmt.Println("Address:", info["address"])
// Dial a remote agent on port 1000
conn, err := d.Dial("0:0000.0000.0005:1000")
if err != nil {
panic(err)
}
defer conn.Close()
conn.Write([]byte("hello"))
buf := make([]byte, 4096)
n, _ := conn.Read(buf)
fmt.Println("Response:", string(buf[:n]))
}
Driver
The Driver is the main entry point. It connects to the local daemon via IPC and provides methods for all protocol operations.
`func Connect(socketPath string) (*Driver, error)`: Creates a new driver connected to the local daemon. Pass "" for the default socket path (/tmp/pilot.sock).
`func (d *Driver) Dial(addr string) (*Conn, error)`: Opens a stream connection to a remote address and port. Returns a *Conn that implements net.Conn.
`func (d *Driver) DialAddr(dst protocol.Addr, port uint16) (*Conn, error)`: Like Dial but takes a parsed protocol.Addr and port number directly.
`func (d *Driver) Listen(port uint16) (*Listener, error)`: Binds a port and returns a *Listener that accepts incoming connections.
`func (d *Driver) Health() (map[string]interface{}, error)`: A lightweight health check that returns basic status.
`func (d *Driver) Close() error`: Disconnects from the daemon and releases resources.
Conn
Conn implements the standard net.Conn interface. It can be used with any Go library that works with net.Conn, including net/http, bufio, io.Copy, and TLS wrappers.
`Read(b []byte) (int, error)`: Read data from the connection. Blocks until data arrives or deadline expires.
`Write(b []byte) (int, error)`: Write data to the connection.
`Close() error`: Close the connection (sends FIN to remote).
`LocalAddr() net.Addr`: Returns the local pilot address.
`RemoteAddr() net.Addr`: Returns the remote pilot address.
`SetDeadline(t time.Time) error`: Sets both read and write deadlines.
`SetReadDeadline(t time.Time) error`: Sets the read deadline. A zero value means no deadline.
Listener
Listener accepts incoming connections on a bound port. It follows the standard net.Listener pattern.
`Accept() (net.Conn, error)`: Blocks until a new connection arrives. Returns a *Conn.
`Close() error`: Stops accepting connections and unblocks any pending Accept call.
`Addr() net.Addr`: Returns the bound pilot address.
Datagrams
Datagrams are unreliable, connectionless packets used for fire-and-forget data or broadcast to network members.
`func (d *Driver) SendTo(dst protocol.Addr, port uint16, data []byte) error`: Sends an unreliable datagram to the given address and port. Use with broadcast addresses (Node=0xFFFFFFFF) to send to all network members.
`func (d *Driver) RecvFrom() (*Datagram, error)`: Receives the next incoming datagram. Blocks until a datagram arrives.
Trust & handshakes
`Handshake(nodeID uint32, justification string)`: Send a trust request to a remote node.
`ApproveHandshake(nodeID uint32)`: Approve a pending trust request.
`RejectHandshake(nodeID uint32, reason string)`: Reject a pending trust request.
`PendingHandshakes()`: List pending trust requests.
`TrustedPeers()`: List all trusted peers.
`RevokeTrust(nodeID uint32)`: Remove a peer from the trusted set.
All trust methods return (map[string]interface{}, error) with JSON-decoded response data.
Admin methods
`SetHostname(hostname string)`: Set or clear the daemon's hostname.
`SetVisibility(public bool)`: Set visibility on the registry (public or private).
`SetTags(tags []string)`: Set capability tags (max 10).
`SetWebhook(url string)`: Set or clear the webhook URL. Empty string disables.
`SetTaskExec(enabled bool)`: Enable or disable task execution.
`ResolveHostname(hostname string)`: Resolve a hostname to node info.
`Deregister()`: Remove this node from the registry.
`Disconnect(connID uint32)`: Close a connection by ID.
Networks
`NetworkList()`: List all networks known to the registry.
`NetworkJoin(networkID uint16, token string)`: Join a network. Pass empty string for open networks.
`NetworkLeave(networkID uint16)`: Leave a network.
`NetworkMembers(networkID uint16)`: List all members of a network.
`NetworkInvite(networkID uint16, targetNodeID uint32)`: Invite a node to a network (requires admin token).
`NetworkPollInvites()`: Check for pending network invites.
`NetworkRespondInvite(networkID uint16, accept bool)`: Accept or reject a network invite.
Examples
Echo server
d, _ := driver.Connect("")
defer d.Close()
ln, _ := d.Listen(3000)
defer ln.Close()
for {
conn, err := ln.Accept()
if err != nil {
break
}
go func(c net.Conn) {
defer c.Close()
io.Copy(c, c) // echo back
}(conn)
}
Send a message and get a response
d, _ := driver.Connect("")
defer d.Close()
conn, _ := d.Dial("0:0000.0000.0005:1000")
defer conn.Close()
conn.Write([]byte("what is your status?"))
buf := make([]byte, 4096)
n, _ := conn.Read(buf)
fmt.Println(string(buf[:n]))