AvyOS Docs
Documentation Home

avyos.dev/pkg/sutra

package sutra

Package Overview

Package sutra provides an IPC framework for inter-process communication.

Export GroupCount
Constants5
Variables0
Functions3
Types7

Constants

const (
	IDBus       uint32 = 0          // Deprecated bus ID (kept for compatibility)
	IDService   uint32 = 0x00000001 // Service endpoint ID
	IDClient    uint32 = 0x80000000 // Client ID range start
	IDBroadcast uint32 = 0xFFFFFFFF // Broadcast to all
)

Well-known endpoint IDs.

const (
	EventRegister    uint16 = 0x0001 // Deprecated
	EventUnregister  uint16 = 0x0002 // Deprecated
	EventConnect     uint16 = 0x0003 // Client connected
	EventDisconnect  uint16 = 0x0004 // Client disconnected
	EventPing        uint16 = 0x0005 // Deprecated
	EventPong        uint16 = 0x0006 // Deprecated
	EventError       uint16 = 0x0007 // Error response
	EventLookup      uint16 = 0x0008 // Deprecated
	EventLookupReply uint16 = 0x0009 // Deprecated
	EventUserBase    uint16 = 0x0100 // Start of user-defined events

	// Service control events (init system)
	EventInitServiceStart    uint16 = 0x0110 // Start a service
	EventInitServiceStop     uint16 = 0x0111 // Stop a service
	EventInitServiceRestart  uint16 = 0x0112 // Restart a service
	EventInitServiceStatus   uint16 = 0x0113 // Get service status
	EventInitServiceList     uint16 = 0x0114 // List all services
	EventInitServicePoweroff uint16 = 0x115  // Power off system
	EventInitServiceReboot   uint16 = 0x116  // Reboot system
)

Event types. Bus events are deprecated and kept for compatibility.

const DefaultSocketPath = "/cache/runtime/sutra.sock"

DefaultSocketPath is the legacy default Sutra socket path.

const HeaderSize = 12 // 4 + 4 + 2 + 2

HeaderSize is the size of the transaction header in bytes

const MaxPayloadSize = 65535

MaxPayloadSize is the maximum payload size

Functions

func DecodeString(data []byte) (string, int)

DecodeString decodes a length-prefixed string

func EncodeString(s string) []byte

EncodeString encodes a string with length prefix

func EncodeUint32(v uint32) []byte

EncodeUint32 encodes a uint32 as payload bytes

Types

Client

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

Client represents a connection to a service endpoint.

Functions

func Connect(socketPath string) (*Client, error)

Connect connects to a service endpoint socket.

func ConnectTCP(address string) (*Client, error)

ConnectTCP connects to a service endpoint over TCP.

Methods

func (c *Client) Broadcast(event uint16, payload []byte) error

Broadcast sends a broadcast transaction handled by the target service.

func (c *Client) Call(dest uint32, event uint16, payload []byte, timeout time.Duration) (*Transaction, error)

Call sends a transaction and waits for a response.

func (c *Client) Close() error

Close closes the client connection.

func (c *Client) IsConnected() bool

IsConnected returns true if the client is connected.

func (c *Client) Lookup(name string) (uint32, error)

Lookup is unsupported in decentralized mode.

func (c *Client) Off(event uint16)

Off removes an event handler.

func (c *Client) On(event uint16, handler EventHandler)

On registers an event handler.

func (c *Client) OnDisconnect(fn func())

OnDisconnect sets the disconnection callback.

func (c *Client) Ping() error

Ping is unsupported in decentralized mode.

func (c *Client) Send(dest uint32, event uint16, payload []byte) error

Send sends a transaction without waiting for response.

Decoder

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

Decoder reads primitive values from a binary buffer. It uses a sticky-error pattern: after the first error, all reads return zero values.

Functions

func NewDecoder(data []byte) *Decoder

NewDecoder creates a decoder over the given byte slice.

Methods

func (d *Decoder) Bool() bool
func (d *Decoder) Bytes() []byte
func (d *Decoder) Err() error

Err returns the first error encountered during decoding, or nil.

func (d *Decoder) Int() int
func (d *Decoder) Int32() int32
func (d *Decoder) Rune() rune
func (d *Decoder) String() string
func (d *Decoder) Uint16() uint16
func (d *Decoder) Uint32() uint32
func (d *Decoder) Uint64() uint64
func (d *Decoder) Uint8() uint8

Encoder

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

Encoder writes primitive values into a binary buffer. All integers are little-endian. Strings are length-prefixed (2-byte LE length).

Functions

func NewEncoder(capacity int) *Encoder

NewEncoder creates an encoder with the given initial capacity hint.

Methods

func (e *Encoder) Bytes() []byte

Bytes returns the encoded buffer.

func (e *Encoder) PutBool(v bool)
func (e *Encoder) PutBytes(v []byte)
func (e *Encoder) PutInt(v int)
func (e *Encoder) PutInt32(v int32)
func (e *Encoder) PutRune(v rune)
func (e *Encoder) PutString(v string)
func (e *Encoder) PutUint16(v uint16)
func (e *Encoder) PutUint32(v uint32)
func (e *Encoder) PutUint64(v uint64)
func (e *Encoder) PutUint8(v uint8)

EventHandler

type EventHandler func(t *Transaction)

EventHandler handles incoming events.

MethodHandler

type MethodHandler func(t *Transaction) ([]byte, error)

MethodHandler handles a method call and returns a response.

Service

type Service struct {
	Name string
	ID   uint32
	// contains filtered or unexported fields
}

Service represents a decentralized named service endpoint.

Functions

func NewService(name, socketPath string) (*Service, error)

NewService creates and starts a service endpoint.

func NewServiceTCP(name, address string) (*Service, error)

NewServiceTCP creates and starts a service endpoint on a TCP address.

Methods

func (s *Service) Broadcast(event uint16, payload []byte) error

Broadcast sends an event to all connected clients.

func (s *Service) Call(dest uint32, event uint16, payload []byte, timeout time.Duration) (*Transaction, error)

Call makes a call to a specific client and waits for response.

func (s *Service) Close() error

Close stops the service listener and all client connections.

func (s *Service) GetClientUID(clientID uint32) (uint32, bool)

GetClientUID returns the Unix UID of the process that connected with the given client ID.

func (s *Service) Handle(event uint16, handler MethodHandler)

Handle registers a method handler for an event.

func (s *Service) HandleFunc(event uint16, fn func(payload []byte) ([]byte, error))

HandleFunc registers a simple handler that returns a fixed response.

func (s *Service) IsRunning() bool

IsRunning returns true if the service is running.

func (s *Service) OnDisconnect(fn func())

OnDisconnect sets the disconnection callback.

func (s *Service) Run()

Run blocks until the service is closed.

func (s *Service) Send(dest uint32, event uint16, payload []byte) error

Send sends a message to a destination client.

Transaction

type Transaction struct {
	Sender      uint32 // Sender ID
	Destination uint32 // Destination ID (or broadcast)
	Event       uint16 // Event type
	Payload     []byte // Variable-length payload
}

Transaction represents a message in the Sutra IPC system. Header format: [Sender:4][Destination:4][Event:2][Size:2][Payload:Size]

Functions

func DecodeTransaction(data []byte) (*Transaction, error)

DecodeTransaction decodes a transaction from a byte slice

func NewTransaction(sender, dest uint32, event uint16, payload []byte) *Transaction

NewTransaction creates a new transaction

func ReadTransaction(r io.Reader) (*Transaction, error)

ReadTransaction reads a transaction from an io.Reader

Methods

func (t *Transaction) Encode() []byte

Encode writes the transaction to a byte slice

func (t *Transaction) Error(message string) *Transaction

Error creates an error reply

func (t *Transaction) PayloadString() string

PayloadString returns payload as string

func (t *Transaction) PayloadUint32() uint32

PayloadUint32 returns first 4 bytes of payload as uint32

func (t *Transaction) Reply(event uint16, payload []byte) *Transaction

Reply creates a reply transaction to this one

func (t *Transaction) Size() uint16

Size returns the payload size

func (t *Transaction) TotalSize() int

TotalSize returns the total transaction size including header

func (t *Transaction) WriteTo(w io.Writer) (int64, error)

WriteTo writes the transaction to an io.Writer