Help us shape the future of Go! Take the 2026 Go Developer Survey

bridge

package
v0.19.12 Latest Latest
Warning

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

 Go to latest Published: Oct 22, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package bridge owns connectivity authority, never agent execution or sessions, and defines the non-owning, versioned Orb instance attachments it routes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Code added in v0.11.0 

func Code(err error) string

func ConnectClient added in v0.11.0 

func ConnectClient(ctx context.Context, stream net.Conn, key ed25519.PrivateKey, expected string) (*protocol.Conn, error)

ConnectClient opens an outbound-only connection. It starts no listener or Bridge service, and rejects remote calls into the client. The caller owns key storage.

func Fail added in v0.11.0 

func Fail(code string) error

func InvitationCode added in v0.19.3 

func InvitationCode(inv Invitation) string

InvitationCode is what a joining device copies or scans: only what it uses, so grants stay with the inviter and the QR code stays small.

func JSON added in v0.11.0 

func JSON(v any) json.RawMessage

func Keepalive added in v0.19.1 

func Keepalive(ctx context.Context, c *protocol.Conn, every time.Duration)

keepalive pings a peer connection until the connection or the service ends, and closes it when the peer stops answering. A peer that restarted or lost its network leaves a half-open connection behind; without this, the next call on it would wait out its timeout before anything redialled.

func ParsePeerID 

func ParsePeerID(id string) (ed25519.PublicKey, error)

func PeerID 

func PeerID(key ed25519.PublicKey) string

func ValidateCall added in v0.11.0 

func ValidateCall(c Call) error

Types

type Bridge 

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

func Open 

func Open(store document.Document, create bool) (*Bridge, error)

func (*Bridge) AddGrant 

func (b *Bridge) AddGrant(g Grant) error

func (*Bridge) Admin 

func (b *Bridge) Admin(_ context.Context, method string, params json.RawMessage) (json.RawMessage, error)

Admin is deliberately absent from the remote routing table. Hosts expose it only after local-owner authentication.

func (*Bridge) Allowed 

func (b *Bridge) Allowed(p Principal, id, permission string) bool

func (*Bridge) Approve 

func (b *Bridge) Approve(id, claimant string) error

func (*Bridge) Attach 

func (b *Bridge) Attach(id, credential, boot string, endpoint Endpoint) (string, error)

func (*Bridge) Authorize 

func (b *Bridge) Authorize(r Request) bool

func (*Bridge) Available 

func (b *Bridge) Available(id string) bool

func (*Bridge) Block 

func (b *Bridge) Block(peer string) error

func (*Bridge) Call 

func (b *Bridge) Call(ctx context.Context, p Principal, call Call) (json.RawMessage, error)

func (*Bridge) Catalog 

func (b *Bridge) Catalog(p Principal) []Instance

func (*Bridge) Changes 

func (b *Bridge) Changes() <-chan struct{}

func (*Bridge) Claim 

func (b *Bridge) Claim(peer, id, token string, locators ...string) (Invitation, error)

func (*Bridge) Close 

func (b *Bridge) Close() error

func (*Bridge) Connect 

func (b *Bridge) Connect(ctx context.Context, stream net.Conn, expected string, server bool) (*protocol.Conn, string, error)

Connect authenticates a caller-supplied stream. It never creates a listener, locates a profile, or starts an agent runtime.

func (*Bridge) Connection 

func (b *Bridge) Connection(peer string) *protocol.Conn

Connection returns an existing authenticated channel in either direction.

func (*Bridge) Contacts 

func (b *Bridge) Contacts(peer, scope string) ([]Record, error)

func (*Bridge) Detach 

func (b *Bridge) Detach(id, generation string)

func (*Bridge) Enroll 

func (b *Bridge) Enroll(alias, group string) (Instance, string, error)

func (*Bridge) Handle 

func (b *Bridge) Handle(ctx context.Context, peer, method string, params json.RawMessage) (json.RawMessage, error)

func (*Bridge) Hello 

func (b *Bridge) Hello() Hello

func (*Bridge) Invite 

func (b *Bridge) Invite(grants []Grant) (Invitation, error)

func (*Bridge) Known added in v0.13.2 

func (b *Bridge) Known(peer string) bool

Known reports whether peer is one this Bridge deals with beyond pairing: a saved peer, one holding a grant, or a member of a scope.

func (*Bridge) MergeContact 

func (b *Bridge) MergeContact(sender string, r Record) (bool, error)

func (*Bridge) Outbound 

func (b *Bridge) Outbound(instance, peer string, call Call) (Subject, error)

func (*Bridge) PairStatus 

func (b *Bridge) PairStatus(peer, id string) (Invitation, error)

func (*Bridge) PeerID 

func (b *Bridge) PeerID() string

func (*Bridge) PeerLocator 

func (b *Bridge) PeerLocator(peer string) (string, error)

func (*Bridge) PersonalGroup 

func (b *Bridge) PersonalGroup() string

func (*Bridge) Principal 

func (b *Bridge) Principal() Principal

func (*Bridge) PublishContact 

func (b *Bridge) PublishContact(scope, name string, endpoints []Locator, withdraw bool) (Record, error)

func (*Bridge) Retire added in v0.12.1 

func (b *Bridge) Retire(ids []string) (int, error)

Retire removes the named instances or, with none named, every throwaway instance whose Orb has gone: one that attached once, is not attached now, and no grant names. It returns how many it removed.

func (*Bridge) SavePeer 

func (b *Bridge) SavePeer(peer, locator string) error

func (*Bridge) SaveTransportState 

func (b *Bridge) SaveTransportState(raw json.RawMessage) error

func (*Bridge) SetHost added in v0.13.0 

func (b *Bridge) SetHost(h Host)

func (*Bridge) SetName added in v0.19.3 

func (b *Bridge) SetName(name string)

SetName is what this machine is called on its peers' screens ("Baudouin's MacBook Pro").

func (*Bridge) SetScope 

func (b *Bridge) SetScope(id string, peers []string) error

func (*Bridge) TLSConfig 

func (b *Bridge) TLSConfig(expected string, server bool) (*tls.Config, error)

func (*Bridge) TransportState 

func (b *Bridge) TransportState() json.RawMessage

type Call added in v0.11.0 

type Call struct {
	InstanceID  string          `json:"instance_id"`
	Service     string          `json:"service"`
	Method      string          `json:"method"`
	SessionID   string          `json:"session_id,omitempty"`
	Expected    Expected        `json:"expected"`
	OperationID string          `json:"operation_id,omitempty"`
	Args        json.RawMessage `json:"args"`
}

type Contact 

type Contact struct {
	Schema     string                     `json:"schema"`
	Scope      string                     `json:"scope_id"`
	Peer       string                     `json:"peer_id"`
	Revision   string                     `json:"revision"`
	Name       string                     `json:"display_name"`
	Protocols  []string                   `json:"protocols"`
	Endpoints  []Locator                  `json:"endpoints"`
	Withdrawn  bool                       `json:"withdrawn"`
	Extensions map[string]json.RawMessage `json:"extensions,omitempty"`
}

type Endpoint added in v0.11.0 

type Endpoint interface {
	Invoke(context.Context, string, json.RawMessage) (json.RawMessage, error)
	Close() error
}

Endpoint is implemented by in-process attachments and native IPC clients. Close releases remote availability; it never disposes the attached runtime.

type Error added in v0.11.0 

type Error struct {
	Kind string `json:"kind"`
}

func (*Error) Error added in v0.11.0 

func (e *Error) Error() string

type Event added in v0.11.0 

type Event struct {
	Cursor string          `json:"cursor"`
	Data   json.RawMessage `json:"data"`
}

type Expected added in v0.11.0 

type Expected struct {
	Generation string `json:"registration_generation"`
	Revision   string `json:"session_revision"`
}

type Grant 

type Grant struct {
	ID            string    `json:"grant_id,omitempty"`
	Principal     Principal `json:"principal"`
	GroupID       string    `json:"group_id,omitempty"`
	IncludeFuture bool      `json:"include_future"`
	Instances     []string  `json:"instances,omitempty"`
	Permissions   []string  `json:"permissions"`
	Destination   string    `json:"destination,omitempty"`
}

func ConversationGrant added in v0.19.1 

func ConversationGrant(peer string) Grant

ConversationGrant is control of every conversation without the machine: what a joining Orb gives back to the Orb it joined, which never asked for more.

func FullGrant added in v0.19.1 

func FullGrant(peer string) Grant

FullGrant is what an invitation offers: control of every conversation, current and future, and of the machine itself (host.launch: its threads, starting Orb, updating it).

type Hello 

type Hello struct {
	PeerID   string `json:"peer_id"`
	BootID   string `json:"bridge_boot_id"`
	Protocol string `json:"protocol"`
	MaxFrame int    `json:"max_frame"`
	MaxPage  int    `json:"max_page"`
}

type Host added in v0.13.0 

type Host func(ctx context.Context, p Principal, method string, params json.RawMessage) (json.RawMessage, error)

Host serves a peer's machine-level calls — the threads stored on this machine, and starting Orb in a folder — for principals whose grant includes host.launch.

type Instance 

type Instance struct {
	ID         string `json:"instance_id"`
	Alias      string `json:"alias"`
	Group      string `json:"group_id"`
	Generation string `json:"registration_generation"`
	Credential string `json:"credential_hash,omitempty"`
	BootID     string `json:"boot_id,omitempty"`
	Available  bool   `json:"available"`
}

type Invitation 

type Invitation struct {
	ClaimantLocator string  `json:"claimant_locator,omitempty"`
	ID              string  `json:"invitation_id"`
	PeerID          string  `json:"peer_id"`
	Token           string  `json:"token,omitempty"`
	Locator         string  `json:"locator,omitempty"`
	Expires         int64   `json:"expires"`
	Grants          []Grant `json:"grants"`
	Claimant        string  `json:"claimant,omitempty"`
	Status          string  `json:"status"`
}

func ParseInvitation added in v0.19.3 

func ParseInvitation(text string) (Invitation, error)

ParseInvitation reads an invitation from its code, its JSON, or a message that holds the code.

type Ledger added in v0.11.0 

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

func OpenLedger added in v0.11.0 

func OpenLedger(store document.Document, quota int) (*Ledger, error)

func (*Ledger) Accept added in v0.11.0 

func (l *Ledger) Accept(r Request) (Receipt, bool, error)

func (*Ledger) Get added in v0.11.0 

func (l *Ledger) Get(p Principal, instance, op string) (Receipt, error)

func (*Ledger) Set added in v0.11.0 

func (l *Ledger) Set(r Request, status string, result json.RawMessage, code string) (Receipt, error)

type Local added in v0.11.0 

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

Local is a non-owning in-process registration channel. Closing it fences delivery without closing the runtime adapter or its operation ledger.

func NewLocal added in v0.11.0 

func NewLocal(handler func(context.Context, string, json.RawMessage) (json.RawMessage, error)) *Local

func (*Local) Close added in v0.11.0 

func (l *Local) Close() error

func (*Local) Invoke added in v0.11.0 

func (l *Local) Invoke(ctx context.Context, method string, p json.RawMessage) (json.RawMessage, error)

type Locator 

type Locator struct {
	Transport string `json:"transport"`
	Locator   string `json:"locator"`
}

type Model added in v0.11.0 

type Model struct {
	ID       string   `json:"id"`
	Provider string   `json:"provider"`
	Name     string   `json:"name"`
	Thinking []string `json:"thinking,omitempty"`
}

type Peers added in v0.19.1 

type Peers struct {
	Bridge *Bridge
	// Dial opens a stream to peer at locator.
	Dial func(ctx context.Context, peer, locator string) (net.Conn, error)
	// Locator is where peers reach this Bridge; WebURL, when set, replaces it
	// in invitations.
	Locator func() (string, error)
	WebURL  string
	// Forget drops what this machine keeps of a peer the owner blocked.
	Forget func(ctx context.Context, peer string) error
	// contains filtered or unexported fields
}

Peers keeps a Bridge's channels to its peers over the transports its host supplies: it dials them, retries a call once on a fresh channel, pings channels so dead ones close, greets known peers at start, exchanges contact records with scope members, and serves the owner calls that need the network (invite, join, remote, publish).

func NewPeers added in v0.19.1 

func NewPeers(ctx context.Context, b *Bridge) *Peers

NewPeers serves b's peers until ctx ends.

func (*Peers) Admin added in v0.19.1 

func (ps *Peers) Admin(ctx context.Context, method string, params json.RawMessage) (json.RawMessage, error)

func (*Peers) Greet added in v0.19.1 

func (ps *Peers) Greet()

func (*Peers) Peer added in v0.19.1 

func (ps *Peers) Peer(ctx context.Context, id, locator string) (*protocol.Conn, error)

func (*Peers) Reconcile added in v0.19.1 

func (ps *Peers) Reconcile()

func (*Peers) Remote added in v0.19.1 

func (ps *Peers) Remote(ctx context.Context, id, method string, p any) (json.RawMessage, error)

type Principal added in v0.11.0 

type Principal struct {
	PeerID  string  `json:"peer_id"`
	Subject Subject `json:"subject"`
}

type Receipt added in v0.11.0 

type Receipt struct {
	InstanceID  string          `json:"instance_id"`
	SessionID   string          `json:"session_id,omitempty"`
	Method      string          `json:"method"`
	Expected    Expected        `json:"expected"`
	AcceptedAt  int64           `json:"accepted_at"`
	OperationID string          `json:"operation_id"`
	Status      string          `json:"status"`
	Result      json.RawMessage `json:"result,omitempty"`
	Error       string          `json:"error,omitempty"`
	Digest      string          `json:"digest"`
}

type Record 

type Record struct {
	Payload   string `json:"payload"`
	Signature string `json:"signature"`
}

func (Record) Verify 

func (r Record) Verify() (Contact, error)

type Request added in v0.11.0 

type Request struct {
	PageLimit  int       `json:"page_limit,omitempty"`
	Principal  Principal `json:"principal"`
	Generation string    `json:"generation"`
	Call       Call      `json:"call"`
}

type Stream added in v0.11.0 

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

func NewStream added in v0.11.0 

func NewStream(limit, quota int) *Stream

func (*Stream) Cursor added in v0.14.0 

func (s *Stream) Cursor() string

Cursor names the position after the last published event.

func (*Stream) Publish added in v0.11.0 

func (s *Stream) Publish(data json.RawMessage)

func (*Stream) Replay added in v0.11.0 

func (s *Stream) Replay(cursor string) ([]Event, error)

type Subject added in v0.11.0 

type Subject struct {
	Kind       string `json:"kind"`
	InstanceID string `json:"instance_id,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis
Package protocol implements the bounded, strict JSON stream used by Orb Bridge.
 Package protocol implements the bounded, strict JSON stream used by Orb Bridge.
Package view is the client every Orb app draws.
 Package view is the client every Orb app draws.

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.