client

package
v1.10.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BinaryClient 

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

BinaryClient talks to a registry server using the binary wire protocol. It provides native binary encoding for hot-path operations (heartbeat, lookup, resolve) and JSON-over-binary passthrough for all other operations.

func DialBinary 

func DialBinary(addr string) (*BinaryClient, error)

DialBinary connects to a registry server and negotiates the binary wire protocol. The server detects the magic bytes and switches to binary mode for this connection.

func (*BinaryClient) Addr 

func (c *BinaryClient) Addr() string

Addr returns the registry address this client is connected to.

func (*BinaryClient) Close 

func (c *BinaryClient) Close() error

Close shuts down the binary client connection.

func (*BinaryClient) Heartbeat 

func (c *BinaryClient) Heartbeat(nodeID uint32, sig []byte) (unixTime int64, keyExpiryWarning bool, err error)

Heartbeat sends a binary heartbeat and returns the server time and key expiry warning.

func (*BinaryClient) Lookup 

func (c *BinaryClient) Lookup(nodeID uint32) (*wire.LookupResult, error)

Lookup sends a binary lookup request and returns the decoded result.

func (*BinaryClient) Resolve 

func (c *BinaryClient) Resolve(nodeID, requesterID uint32, sig []byte) (*wire.ResolveResult, error)

Resolve sends a binary resolve request and returns the decoded result.

func (*BinaryClient) SendJSON 

func (c *BinaryClient) SendJSON(msg map[string]interface{}) (map[string]interface{}, error)

SendJSON sends a JSON message over the binary protocol using JSON passthrough. This allows any registry operation to be used without a native binary encoding.

type Client 

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

Client talks to a registry server over TCP (optionally TLS). It automatically reconnects if the connection drops.

By default a Client owns a single TCP connection (Dial / DialTLS / DialTLSPinned). Each Send takes c.mu and serialises the entire request/response round-trip on that one conn. Under heavy concurrent load (the §4.8 lock-graph stress harness — 250 heartbeat goroutines per daemon hammering Health / Info / SetTags / ResolveHostname plus the per-resolve prewarm goroutines and persistHostnameCache writers, all funnelling through regConn.Send) that single mutex becomes the bottleneck: in-flight calls cannot honour shutdown signals because they're queued behind the mutex.

DialPool / DialTLSPool create a Client backed by a small pool of connections (the primary c.conn plus N-1 secondary conns). Each concurrent Send picks a free pooled conn (blocking only if every conn is in use), eliminating the head-of-line wait. The primary c.conn / c.mu / c.closed fields are retained for backward compatibility with tests that touch them directly.

func Dial 

func Dial(addr string) (*Client, error)

func DialPool 

func DialPool(addr string, size int) (*Client, error)

DialPool connects to a registry server over plain TCP and pre-warms a pool of `size` connections (size >= 1). When size == 1 this is identical to Dial. When size > 1, additional secondary conns are dialed; concurrent Send calls then run in parallel up to `size` at a time, instead of all queueing on a single mutex.

DialPool exists to fix #93 (regConn fairness under sustained load): the daemon's IPC handlers spawn goroutines that all call regConn.Send and previously serialised on c.mu. With DialPool the daemon can keep the same code path while letting up to `size` registry round-trips run concurrently.

On any pool conn dial failure DialPool closes the conns it had already opened and returns an error.

func DialTLS 

func DialTLS(addr string, tlsConfig *tls.Config) (*Client, error)

DialTLS connects to a registry server over TLS. A non-nil tlsConfig is required. For certificate pinning, use DialTLSPinned.

func DialTLSPinned 

func DialTLSPinned(addr, fingerprint string) (*Client, error)

DialTLSPinned connects to a registry server over TLS with certificate pinning. The fingerprint is a hex-encoded SHA-256 hash of the server's DER-encoded certificate.

func DialTLSPool 

func DialTLSPool(addr string, tlsConfig *tls.Config, size int) (*Client, error)

DialTLSPool is the TLS variant of DialPool.

func (*Client) CheckTrust 

func (c *Client) CheckTrust(nodeA, nodeB uint32) (bool, error)

CheckTrust checks if a trust pair or shared network exists between two nodes.

func (*Client) ClearKeyExpiryAdmin 

func (c *Client) ClearKeyExpiryAdmin(nodeID uint32, adminToken string) (map[string]interface{}, error)

ClearKeyExpiryAdmin removes the key expiry from a node using admin token auth.

func (*Client) Close 

func (c *Client) Close() error

func (*Client) CreateManagedNetwork 

func (c *Client) CreateManagedNetwork(nodeID uint32, name, joinRule, token, adminToken string, enterprise bool, rules string, networkAdminToken ...string) (map[string]interface{}, error)

CreateManagedNetwork creates a network with managed rules.

func (*Client) CreateNetwork 

func (c *Client) CreateNetwork(nodeID uint32, name, joinRule, token, adminToken string, enterprise bool, networkAdminToken ...string) (map[string]interface{}, error)

func (*Client) DeleteNetwork 

func (c *Client) DeleteNetwork(networkID uint16, adminToken string, nodeID ...uint32) (map[string]interface{}, error)

func (*Client) DemoteMember 

func (c *Client) DemoteMember(networkID uint16, nodeID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

DemoteMember demotes an admin to member. Only the owner can demote.

func (*Client) Deregister 

func (c *Client) Deregister(nodeID uint32) (map[string]interface{}, error)

func (*Client) DeregisterAdmin 

func (c *Client) DeregisterAdmin(nodeID uint32, adminToken string) (map[string]interface{}, error)

DeregisterAdmin removes a node using admin token auth.

func (*Client) DirectoryStatus 

func (c *Client) DirectoryStatus(networkID uint16, adminToken string) (map[string]interface{}, error)

DirectoryStatus returns directory sync status for a network.

func (*Client) DirectorySync 

func (c *Client) DirectorySync(networkID uint16, entries []map[string]interface{}, removeUnlisted bool, adminToken string) (map[string]interface{}, error)

DirectorySync pushes a directory listing to update RBAC roles and membership.

func (*Client) GetAuditExport 

func (c *Client) GetAuditExport(adminToken string) (map[string]interface{}, error)

GetAuditExport returns the current audit export configuration. Requires admin token.

func (*Client) GetAuditLog 

func (c *Client) GetAuditLog(networkID uint16, adminToken string) (map[string]interface{}, error)

GetAuditLog returns recent audit entries from the registry.

func (*Client) GetExprPolicy 

func (c *Client) GetExprPolicy(networkID uint16) (map[string]interface{}, error)

GetExprPolicy returns the programmable policy for a network.

func (*Client) GetIDPConfig 

func (c *Client) GetIDPConfig(adminToken string) (map[string]interface{}, error)

GetIDPConfig returns the current identity provider configuration. Requires admin token.

func (*Client) GetIdentity 

func (c *Client) GetIdentity(nodeID uint32, adminToken string) (map[string]interface{}, error)

GetIdentity returns the external identity of a node. Requires admin token.

func (*Client) GetKeyInfo 

func (c *Client) GetKeyInfo(nodeID uint32) (map[string]interface{}, error)

GetKeyInfo returns key lifecycle metadata for a node.

func (*Client) GetMemberRole 

func (c *Client) GetMemberRole(networkID uint16, targetNodeID uint32) (map[string]interface{}, error)

GetMemberRole returns the RBAC role of a node in a network.

func (*Client) GetMemberTags 

func (c *Client) GetMemberTags(netID uint16, targetNodeID uint32) (map[string]interface{}, error)

GetMemberTags returns admin-assigned member tags for a node (or all members if targetNodeID=0).

func (*Client) GetNetworkPolicy 

func (c *Client) GetNetworkPolicy(networkID uint16) (map[string]interface{}, error)

GetNetworkPolicy returns the policy for a given network.

func (*Client) GetProvisionStatus 

func (c *Client) GetProvisionStatus(adminToken string) (map[string]interface{}, error)

GetProvisionStatus returns per-network provisioning status. Requires admin token.

func (*Client) GetWebhook 

func (c *Client) GetWebhook(adminToken string) (map[string]interface{}, error)

GetWebhook returns the current webhook configuration.

func (*Client) GetWebhookDLQ 

func (c *Client) GetWebhookDLQ(adminToken string) (map[string]interface{}, error)

GetWebhookDLQ returns the dead letter queue (failed webhook events).

func (*Client) Heartbeat 

func (c *Client) Heartbeat(nodeID uint32) (map[string]interface{}, error)

func (*Client) InviteToNetwork 

func (c *Client) InviteToNetwork(networkID uint16, inviterID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

InviteToNetwork stores a pending invite for a target node to join an invite-only network.

func (*Client) JoinNetwork 

func (c *Client) JoinNetwork(nodeID uint32, networkID uint16, token string, inviterID uint32, adminToken string) (map[string]interface{}, error)

func (*Client) KickMember 

func (c *Client) KickMember(networkID uint16, nodeID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

KickMember removes a member from a network. Requires owner or admin role.

func (*Client) LeaveNetwork 

func (c *Client) LeaveNetwork(nodeID uint32, networkID uint16, adminToken string) (map[string]interface{}, error)

func (*Client) ListNetworks 

func (c *Client) ListNetworks(adminToken ...string) (map[string]interface{}, error)

ListNetworks returns the registry's network catalog. Member counts (the `members` field on each entry) are admin-only — pass a non-empty adminToken to receive them; otherwise the field is omitted.

func (*Client) ListNodes 

func (c *Client) ListNodes(networkID uint16, adminToken ...string) (map[string]interface{}, error)

func (*Client) Lookup 

func (c *Client) Lookup(nodeID uint32) (map[string]interface{}, error)

func (*Client) PollHandshakes 

func (c *Client) PollHandshakes(nodeID uint32) (map[string]interface{}, error)

PollHandshakes retrieves and clears pending handshake requests for a node. H3 fix: includes a signature to prove node identity.

func (*Client) PollInvites 

func (c *Client) PollInvites(nodeID uint32) (map[string]interface{}, error)

PollInvites returns and clears pending network invites for a node. Signed.

func (*Client) PromoteMember 

func (c *Client) PromoteMember(networkID uint16, nodeID, targetNodeID uint32, adminToken string) (map[string]interface{}, error)

PromoteMember promotes a network member to admin. Only the owner can promote.

func (*Client) ProvisionNetwork 

func (c *Client) ProvisionNetwork(blueprint map[string]interface{}, adminToken string) (map[string]interface{}, error)

ProvisionNetwork applies a network blueprint. Requires admin token.

func (*Client) Punch 

func (c *Client) Punch(requesterID, nodeA, nodeB uint32) (map[string]interface{}, error)

func (*Client) Register 

func (c *Client) Register(listenAddr string) (map[string]interface{}, error)

func (*Client) RegisterWithKey 

func (c *Client) RegisterWithKey(listenAddr, publicKeyB64, owner string, lanAddrs []string, opts ...string) (map[string]interface{}, error)

RegisterWithKey re-registers using an existing Ed25519 public key. The registry returns the same node_id if the key is known. lanAddrs are the node's LAN addresses for same-network peer detection.

func (*Client) RegisterWithKeyOpts 

func (c *Client) RegisterWithKeyOpts(o RegisterOpts) (map[string]interface{}, error)

RegisterWithKeyOpts is the structured-form register call. Existing callers keep using RegisterWithKey; new flags go here.

func (*Client) RegisterWithOwner 

func (c *Client) RegisterWithOwner(listenAddr, owner string) (map[string]interface{}, error)

RegisterWithOwner registers a new node with an owner identifier (email/name) for key rotation recovery.

func (*Client) RenameNetwork 

func (c *Client) RenameNetwork(networkID uint16, name, adminToken string, nodeID ...uint32) (map[string]interface{}, error)

func (*Client) ReportTrust 

func (c *Client) ReportTrust(nodeID, peerID uint32) (map[string]interface{}, error)

func (*Client) RequestHandshake 

func (c *Client) RequestHandshake(fromNodeID, toNodeID uint32, justification, signatureB64 string) (map[string]interface{}, error)

RequestHandshake relays a handshake request through the registry to a target node. This works even for private nodes — no IP exposure needed. M12 fix: includes a signature to prove sender identity.

func (*Client) Resolve 

func (c *Client) Resolve(nodeID, requesterID uint32) (map[string]interface{}, error)

func (*Client) ResolveHostname 

func (c *Client) ResolveHostname(hostname string) (map[string]interface{}, error)

ResolveHostname resolves a hostname to node info (node_id, address, public flag).

func (*Client) ResolveHostnameAs 

func (c *Client) ResolveHostnameAs(requesterID uint32, hostname string) (map[string]interface{}, error)

ResolveHostnameAs resolves a hostname with a requester_id for privacy checks. Private nodes require the requester to have a trust pair or shared network.

func (*Client) RespondHandshake 

func (c *Client) RespondHandshake(nodeID, peerID uint32, accept bool, signatureB64 string) (map[string]interface{}, error)

RespondHandshake approves or rejects a relayed handshake request. If accepted, the registry creates a mutual trust pair. M12 fix: includes a signature to prove responder identity.

func (*Client) RespondInvite 

func (c *Client) RespondInvite(nodeID uint32, networkID uint16, accept bool) (map[string]interface{}, error)

RespondInvite accepts or rejects a pending network invite. Signed.

func (*Client) RevokeTrust 

func (c *Client) RevokeTrust(nodeID, peerID uint32) (map[string]interface{}, error)

func (*Client) RotateKey 

func (c *Client) RotateKey(nodeID uint32, signatureB64, newPubKeyB64 string) (map[string]interface{}, error)

RotateKey requests a key rotation for a node. Requires a signature proving ownership of the current key and the new public key.

func (*Client) Send 

func (c *Client) Send(msg map[string]interface{}) (map[string]interface{}, error)

func (*Client) SetAuditExport 

func (c *Client) SetAuditExport(format, endpoint, token, index, source, adminToken string) (map[string]interface{}, error)

SetAuditExport configures the audit export adapter. Requires admin token.

func (*Client) SetExprPolicy 

func (c *Client) SetExprPolicy(networkID uint16, policyJSON json.RawMessage, adminToken string) (map[string]interface{}, error)

SetExprPolicy sets the programmable policy for a network. Requires owner/admin role or admin token.

func (*Client) SetExternalID 

func (c *Client) SetExternalID(nodeID uint32, externalID, adminToken string) (map[string]interface{}, error)

SetExternalID sets the external identity on a node. Requires admin token.

func (*Client) SetHostname 

func (c *Client) SetHostname(nodeID uint32, hostname string) (map[string]interface{}, error)

SetHostname sets or clears the hostname for a node. An empty hostname clears the current hostname.

func (*Client) SetHostnameAdmin 

func (c *Client) SetHostnameAdmin(nodeID uint32, hostname, adminToken string) (map[string]interface{}, error)

SetHostnameAdmin sets a node's hostname using admin token auth.

func (*Client) SetIDPConfig 

func (c *Client) SetIDPConfig(idpType, url, issuer, clientID, tenantID, domain, adminToken string) (map[string]interface{}, error)

SetIDPConfig configures the identity provider. Requires admin token.

func (*Client) SetIdentityWebhook 

func (c *Client) SetIdentityWebhook(url, adminToken string) (map[string]interface{}, error)

SetIdentityWebhook configures the identity verification webhook URL.

func (*Client) SetKeyExpiry 

func (c *Client) SetKeyExpiry(nodeID uint32, expiresAt time.Time) (map[string]interface{}, error)

SetKeyExpiry sets the key expiry time for a node. Requires signature.

func (*Client) SetKeyExpiryAdmin 

func (c *Client) SetKeyExpiryAdmin(nodeID uint32, expiresAt time.Time, adminToken string) (map[string]interface{}, error)

SetKeyExpiryAdmin sets a node's key expiry using admin token auth.

func (*Client) SetMemberTags 

func (c *Client) SetMemberTags(netID uint16, targetNodeID uint32, tags []string, adminToken string) (map[string]interface{}, error)

SetMemberTags sets admin-assigned tags for a member within a network.

func (*Client) SetNetworkEnterprise 

func (c *Client) SetNetworkEnterprise(networkID uint16, enterprise bool, adminToken string) (map[string]interface{}, error)

func (*Client) SetNetworkPolicy 

func (c *Client) SetNetworkPolicy(networkID uint16, policy map[string]interface{}, adminToken string) (map[string]interface{}, error)

SetNetworkPolicy sets or updates a network's policy. Requires owner/admin role or admin token.

func (*Client) SetSigner 

func (c *Client) SetSigner(fn func(challenge string) string)

SetSigner sets a signing function for authenticated registry operations (H3 fix). The signer receives a challenge string and returns a base64-encoded Ed25519 signature.

Issue #93: when the regConn is pooled (DialPool), multiple Send goroutines may call sign() concurrently while a parallel RotateKey path calls SetSigner. We guard the field with c.mu to keep that race-free; reads via sign() take the same lock so the loaded function pointer is consistent.

func (*Client) SetTags 

func (c *Client) SetTags(nodeID uint32, tags []string) (map[string]interface{}, error)

SetTags sets the capability tags for a node.

func (*Client) SetTagsAdmin 

func (c *Client) SetTagsAdmin(nodeID uint32, tags []string, adminToken string) (map[string]interface{}, error)

SetTagsAdmin sets a node's tags using admin token auth.

func (*Client) SetVisibility 

func (c *Client) SetVisibility(nodeID uint32, public bool) (map[string]interface{}, error)

func (*Client) SetVisibilityAdmin 

func (c *Client) SetVisibilityAdmin(nodeID uint32, public bool, adminToken string) (map[string]interface{}, error)

SetVisibilityAdmin sets a node's visibility using admin token auth.

func (*Client) SetWebhook 

func (c *Client) SetWebhook(url, adminToken string) (map[string]interface{}, error)

SetWebhook configures the registry webhook URL. Pass empty string to disable.

func (*Client) TransferOwnership 

func (c *Client) TransferOwnership(networkID uint16, ownerNodeID, newOwnerID uint32, adminToken string) (map[string]interface{}, error)

TransferOwnership transfers network ownership to another member. Only the current owner can transfer.

func (*Client) ValidateToken 

func (c *Client) ValidateToken(token, adminToken string) (map[string]interface{}, error)

ValidateToken validates a JWT token against the configured IDP. Requires admin token.

type RegisterOpts 

type RegisterOpts struct {
	ListenAddr string
	PublicKey  string // base64 Ed25519
	Owner      string
	LANAddrs   []string
	Version    string
	RelayOnly  bool // task 32: hide real_addr from peers
}

RegisterOpts is the full set of registration options. Lets us add fields (like RelayOnly for task 32) without breaking the variadic signature of RegisterWithKey.

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.