[ Switch to styled version → ]

← Docs index

Go SDK

The driver package is used to build services, custom agents, and integrations in Go.

Installation

go get github.com/TeoSlayer/pilotprotocol

The SDK is in pkg/driver.

import "github.com/TeoSlayer/pilotprotocol/pkg/driver"

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). A custom path can be provided, or the PILOT_SOCKET environment variable can be set.

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

Opens a stream connection to a remote address and port. The address format is "N:XXXX.YYYY.YYYY:PORT". It returns a *Conn that implements net.Conn.

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

This function is like Dial but takes a parsed protocol.Addr and port number.

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

Binds a port and returns a *Listener that accepts incoming connections.

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

Returns the daemon's status: node ID, address, hostname, uptime, peers, connections, encryption status, and traffic stats.

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.

Listener

Listener accepts incoming connections on a bound port. It follows the standard net.Listener pattern.

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.

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

Fans a datagram out to every member of netID. Requires an admin token. Delivery is best-effort.

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

Receives the next incoming datagram, blocking until a datagram arrives.

Trust & handshakes

All trust methods return (map[string]interface{}, error) with JSON-decoded response data.

Admin methods

Networks

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]))

HTTP server over pilot

d, _ := driver.Connect("")
defer d.Close()

ln, _ := d.Listen(80)
defer ln.Close()

http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hello from pilot!")
}))

Because Listener implements net.Listener and Conn implements net.Conn, the standard net/http server works.

Related