wispersgo

package module
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNullPointer           = &Error{Status: StatusNullPointer}
	ErrInvalidUTF8           = &Error{Status: StatusInvalidUTF8}
	ErrStoreError            = &Error{Status: StatusStoreError}
	ErrAlreadyRegistered     = &Error{Status: StatusAlreadyRegistered}
	ErrNotRegistered         = &Error{Status: StatusNotRegistered}
	ErrNotFound              = &Error{Status: StatusNotFound}
	ErrBufferTooSmall        = &Error{Status: StatusBufferTooSmall}
	ErrMissingCallback       = &Error{Status: StatusMissingCallback}
	ErrInvalidActivationCode = &Error{Status: StatusInvalidActivationCode}
	ErrActivationFailed      = &Error{Status: StatusActivationFailed}
	ErrHubError              = &Error{Status: StatusHubError}
	ErrConnectionFailed      = &Error{Status: StatusConnectionFailed}
	ErrTimeout               = &Error{Status: StatusTimeout}
	ErrInvalidState          = &Error{Status: StatusInvalidState}
	ErrUnauthenticated       = &Error{Status: StatusUnauthenticated}
	ErrPeerRejected          = &Error{Status: StatusPeerRejected}
	ErrPeerUnavailable       = &Error{Status: StatusPeerUnavailable}
	ErrRevoked               = &Error{Status: StatusRevoked}
)

Sentinel errors for use with errors.Is().

Functions

This section is empty.

Types

type Error 

type Error struct {
	Status Status
	Detail string // human-readable detail from the Rust library (may be empty)
}

Error wraps a non-success WispersStatus code with optional detail.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Is 

func (e *Error) Is(target error) bool

Is implements errors.Is support so callers can match sentinel values.

type GroupInfo 

type GroupInfo struct {
	ID              string
	Name            *string // nil if the group has no name set
	CreatedAtMillis int64
	State           GroupState
	Nodes           []NodeInfo
}

GroupInfo is a snapshot of the connectivity group's activation state.

type GroupState 

type GroupState int32

GroupState represents the activation state of the connectivity group. 

const (
	GroupStateAlone          GroupState = 0
	GroupStateBootstrap      GroupState = 1
	GroupStateNeedActivation GroupState = 2
	GroupStateCanEndorse     GroupState = 3
	GroupStateAllActivated   GroupState = 4
)

func (GroupState) String 

func (s GroupState) String() string

type IncomingConnections 

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

IncomingConnections wraps a WispersIncomingConnections handle for accepting incoming P2P connections.

func (*IncomingConnections) AcceptQuic 

func (ic *IncomingConnections) AcceptQuic() (*QuicConnection, error)

AcceptQuic waits for an incoming QUIC connection from a peer.

func (*IncomingConnections) AcceptUdp 

func (ic *IncomingConnections) AcceptUdp() (*UdpConnection, error)

AcceptUdp waits for an incoming UDP connection from a peer.

func (*IncomingConnections) Close 

func (ic *IncomingConnections) Close()

Close frees the incoming connections handle.

type Node 

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

Node wraps a WispersNodeHandle and provides operations on a wispers node.

func (*Node) Activate 

func (n *Node) Activate(activationCode string) error

Activate activates the node using an activation code ("node_number-secret"). Requires Registered state.

func (*Node) Close 

func (n *Node) Close()

Close frees the node handle.

func (*Node) ConnectQuic 

func (n *Node) ConnectQuic(peerNodeNumber int32) (*QuicConnection, error)

ConnectQuic connects to a peer node using QUIC transport. Requires Activated state.

func (*Node) ConnectUdp 

func (n *Node) ConnectUdp(peerNodeNumber int32) (*UdpConnection, error)

ConnectUdp connects to a peer node using UDP transport. Requires Activated state.

func (*Node) GroupInfo 

func (n *Node) GroupInfo() (*GroupInfo, error)

GroupInfo returns the group's activation state and node list. Requires Registered or Activated state.

func (*Node) Logout 

func (n *Node) Logout() error

Logout deregisters the node and deletes local state. The Node handle is consumed and must not be used afterward.

func (*Node) RefreshMembership added in v0.10.0 

func (n *Node) RefreshMembership() error

RefreshMembership re-fetches and re-verifies this node's roster and updates cached state to match. Use on a long-running node to proactively detect a revocation that happened while it was active; query State afterward to read the (possibly changed) state. The handle remains usable.

func (*Node) Register 

func (n *Node) Register(token string) error

Register registers the node with the hub using a registration token. Requires Pending state.

func (*Node) RevokeNode added in v0.10.0 

func (n *Node) RevokeNode(targetNodeNumber int32) error

RevokeNode revokes _another_ node from the connectivity group's roster. The caller stays active and the handle remains usable. Revocation is unilateral and irreversible. To revoke yourself, use Logout instead. Requires Activated state.

func (*Node) StartServing 

func (n *Node) StartServing() (*ServingSession, error)

StartServing starts a serving session. Returns a ServingSession whose Incoming field is nil for registered (non-activated) nodes. Requires Registered or Activated state.

func (*Node) State 

func (n *Node) State() NodeState

State returns the current state of the node.

type NodeInfo 

type NodeInfo struct {
	NodeNumber int32
	Name       string
	Metadata   string
	IsSelf     bool
	// State is this node's lifecycle state observed from the local node.
	// NodeStatePending never appears for a listed node.
	State            NodeState
	LastSeenAtMillis int64
	IsOnline         bool
}

NodeInfo contains information about a node in the connectivity group.

type NodeState 

type NodeState int

NodeState represents the state of a wispers node. 

const (
	NodeStatePending    NodeState = 0
	NodeStateRegistered NodeState = 1
	NodeStateActivated  NodeState = 2
	NodeStateRevoked    NodeState = 3
)

func (NodeState) String 

func (s NodeState) String() string

type NodeStorage 

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

NodeStorage wraps a WispersNodeStorageHandle.

func NewInMemoryNodeStorage 

func NewInMemoryNodeStorage() *NodeStorage

NewInMemoryNodeStorage creates a storage backed by in-memory state (for testing).

func NewNodeStorage 

func NewNodeStorage(cb StorageCallbacks) *NodeStorage

NewNodeStorage creates a storage backed by host-provided callbacks.

func (*NodeStorage) Close 

func (s *NodeStorage) Close()

Close frees the storage handle.

func (*NodeStorage) DeleteState 

func (s *NodeStorage) DeleteState() error

DeleteState deletes all persisted state. Used for logout when the node can't be restored (e.g. hub rejected credentials).

func (*NodeStorage) OverrideHubAddr 

func (s *NodeStorage) OverrideHubAddr(addr string) error

OverrideHubAddr overrides the hub address (for testing/staging).

func (*NodeStorage) ReadRegistration 

func (s *NodeStorage) ReadRegistration() (*RegistrationInfo, error)

ReadRegistration reads the local registration data (sync, no hub contact). Returns ErrNotFound if the node is not registered.

func (*NodeStorage) RestoreOrInit 

func (s *NodeStorage) RestoreOrInit() (*Node, NodeState, error)

RestoreOrInit restores or initializes the node state. Returns a Node and its current state. The NodeStorage remains valid after this call.

type QuicConnection 

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

QuicConnection wraps a WispersQuicConnectionHandle.

func (*QuicConnection) AcceptStream 

func (c *QuicConnection) AcceptStream() (*QuicStream, error)

AcceptStream waits for an incoming QUIC stream from the peer.

func (*QuicConnection) Close 

func (c *QuicConnection) Close() error

Close closes the QUIC connection asynchronously, waiting for completion. The handle is consumed.

func (*QuicConnection) OpenStream 

func (c *QuicConnection) OpenStream() (*QuicStream, error)

OpenStream opens a new bidirectional QUIC stream.

type QuicStream 

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

QuicStream wraps a WispersQuicStreamHandle.

func (*QuicStream) Close 

func (s *QuicStream) Close()

Close frees the QUIC stream handle.

func (*QuicStream) Finish 

func (s *QuicStream) Finish() error

Finish sends FIN on the write side. The stream can still be read from.

func (*QuicStream) Read 

func (s *QuicStream) Read(maxLen int) ([]byte, error)

Read reads up to maxLen bytes from the QUIC stream.

func (*QuicStream) Shutdown 

func (s *QuicStream) Shutdown() error

Shutdown stops both sending and receiving on the stream.

func (*QuicStream) Write 

func (s *QuicStream) Write(data []byte) error

Write writes data to the QUIC stream.

type RegistrationInfo 

type RegistrationInfo struct {
	ConnectivityGroupID string
	NodeNumber          int32
	AuthToken           string
	AttestationJWT      string // Signed JWT attesting to (cg_id, node_number)
}

RegistrationInfo contains registration information for a node.

type ServingSession 

type ServingSession struct {
	Incoming *IncomingConnections
	// contains filtered or unexported fields
}

ServingSession wraps a serving handle, session, and optional incoming connections. For registered (non-activated) nodes, Incoming is nil.

func (*ServingSession) Close 

func (s *ServingSession) Close()

Close frees all handles owned by this serving session.

func (*ServingSession) GenerateActivationCode 

func (s *ServingSession) GenerateActivationCode() (string, error)

GenerateActivationCode generates an activation code for endorsing a new node using the default (interactive) profile.

func (*ServingSession) GenerateActivationCodeWithTTL added in v0.9.0 

func (s *ServingSession) GenerateActivationCodeWithTTL(profile TtlProfile) (string, error)

GenerateActivationCodeWithTTL generates an activation code with an explicit TTL profile (e.g. TtlProfileAsynchronous for a long-lived code suitable for out-of-band delivery).

func (*ServingSession) Run 

func (s *ServingSession) Run() error

Run runs the serving session event loop. Blocks until the session ends. The session handle is consumed by this call.

func (*ServingSession) Shutdown 

func (s *ServingSession) Shutdown() error

Shutdown requests the serving session to shut down.

func (*ServingSession) Status added in v0.9.0 

func (s *ServingSession) Status() (*ServingStatus, error)

Status returns a snapshot of the serving session's hub connection and endorsing state. The serving handle is not consumed; it works whether or not the session currently holds a live hub connection.

type ServingStatus added in v0.9.0 

type ServingStatus struct {
	// Connected reports whether the session currently holds a live hub stream.
	// False while it is reconnecting after a hub disconnect.
	Connected           bool
	NodeNumber          int32
	ConnectivityGroupID string
	// CodesOutstanding is the number of activation codes awaiting use.
	CodesOutstanding int
	// NodesAwaitingCosign lists node numbers that have paired and await cosign.
	NodesAwaitingCosign []int32
}

ServingStatus is a snapshot of a serving session's hub connection and endorsing state.

type Status 

type Status int

Status represents a WispersStatus code from the C library. 

const (
	StatusSuccess               Status = 0
	StatusNullPointer           Status = 1
	StatusInvalidUTF8           Status = 2
	StatusStoreError            Status = 3
	StatusAlreadyRegistered     Status = 4
	StatusNotRegistered         Status = 5
	StatusNotFound              Status = 6
	StatusBufferTooSmall        Status = 7
	StatusMissingCallback       Status = 8
	StatusInvalidActivationCode Status = 9
	StatusActivationFailed      Status = 10
	StatusHubError              Status = 11
	StatusConnectionFailed      Status = 12
	StatusTimeout               Status = 13
	StatusInvalidState          Status = 14
	StatusUnauthenticated       Status = 15
	StatusPeerRejected          Status = 16
	StatusPeerUnavailable       Status = 17
	StatusRevoked               Status = 18
)

type StorageCallbacks 

type StorageCallbacks interface {
	LoadRootKey() ([]byte, error)
	SaveRootKey(key []byte) error
	DeleteRootKey() error
	LoadRegistration() ([]byte, error)
	SaveRegistration(data []byte) error
	DeleteRegistration() error
}

StorageCallbacks is the interface that host-provided storage must implement. Return (nil, nil) from Load methods to indicate "not found".

type TtlProfile added in v0.9.0 

type TtlProfile int32

TtlProfile selects the lifetime (and entropy) of a generated activation code. Mirrors the C enum WispersTtlProfile. 

const (
	// TtlProfileInteractive is a short-lived code for live, at-the-keyboard
	// entry (the default).
	TtlProfileInteractive TtlProfile = 0
	// TtlProfileAsynchronous is a long-lived code for out-of-band delivery
	// (e.g. email).
	TtlProfileAsynchronous TtlProfile = 1
)

type UdpConnection 

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

UdpConnection wraps a WispersUdpConnectionHandle.

func (*UdpConnection) Close 

func (c *UdpConnection) Close()

Close closes and frees the UDP connection handle.

func (*UdpConnection) Recv 

func (c *UdpConnection) Recv() ([]byte, error)

Recv receives data from the UDP connection. Blocks until data arrives.

func (*UdpConnection) Send 

func (c *UdpConnection) Send(data []byte) error

Send sends data over the UDP connection. This is synchronous and non-blocking.

Source Files

View all Source files

Directories

Path Synopsis
cmd
fetch-lib command
fetch-lib downloads the prebuilt wispers-connect static library and header for the current platform from GitHub Releases.
 fetch-lib downloads the prebuilt wispers-connect static library and header for the current platform from GitHub Releases.

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.