Handbook
Home Source Code

avyos.dev/pkg/sutra

package sutra

Overview

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

Export GroupCount
Constants5
Variables0
Functions3
Types7

Constants

IDBus, IDService, IDClient, IDBroadcast

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.

EventRegister, EventUnregister, EventConnect, EventDisconnect, EventPing, EventPong, EventError, EventLookup, EventLookupReply, EventUserBase, EventInitServiceStart, EventInitServiceStop, EventInitServiceRestart, EventInitServiceStatus, EventInitServiceList, EventInitServicePoweroff, EventInitServiceReboot

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.

DefaultSocketPath

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

DefaultSocketPath is the legacy default Sutra socket path.

HeaderSize

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

HeaderSize is the size of the transaction header in bytes

MaxPayloadSize

const MaxPayloadSize = 65535

MaxPayloadSize is the maximum payload size

Functions

DecodeString

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

DecodeString decodes a length-prefixed string

EncodeString

func EncodeString(s string) []byte

EncodeString encodes a string with length prefix

EncodeUint32

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

Connect

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

Connect connects to a service endpoint socket.

ConnectTCP

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

ConnectTCP connects to a service endpoint over TCP.

Methods

Broadcast

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

Broadcast sends a broadcast transaction handled by the target service.

Call

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

Call sends a transaction and waits for a response.

Close

func (c *Client) Close() error

Close closes the client connection.

IsConnected

func (c *Client) IsConnected() bool

IsConnected returns true if the client is connected.

Lookup

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

Lookup is unsupported in decentralized mode.

Off

func (c *Client) Off(event uint16)

Off removes an event handler.

On

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

On registers an event handler.

OnDisconnect

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

OnDisconnect sets the disconnection callback.

Ping

func (c *Client) Ping() error

Ping is unsupported in decentralized mode.

Send

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

NewDecoder

func NewDecoder(data []byte) *Decoder

NewDecoder creates a decoder over the given byte slice.

Methods

Bool

func (d *Decoder) Bool() bool

Bytes

func (d *Decoder) Bytes() []byte

Err

func (d *Decoder) Err() error

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

Int

func (d *Decoder) Int() int

Int32

func (d *Decoder) Int32() int32

Rune

func (d *Decoder) Rune() rune

String

func (d *Decoder) String() string

Uint16

func (d *Decoder) Uint16() uint16

Uint32

func (d *Decoder) Uint32() uint32

Uint64

func (d *Decoder) Uint64() uint64

Uint8

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

NewEncoder

func NewEncoder(capacity int) *Encoder

NewEncoder creates an encoder with the given initial capacity hint.

Methods

Bytes

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

Bytes returns the encoded buffer.

PutBool

func (e *Encoder) PutBool(v bool)

PutBytes

func (e *Encoder) PutBytes(v []byte)

PutInt

func (e *Encoder) PutInt(v int)

PutInt32

func (e *Encoder) PutInt32(v int32)

PutRune

func (e *Encoder) PutRune(v rune)

PutString

func (e *Encoder) PutString(v string)

PutUint16

func (e *Encoder) PutUint16(v uint16)

PutUint32

func (e *Encoder) PutUint32(v uint32)

PutUint64

func (e *Encoder) PutUint64(v uint64)

PutUint8

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

NewService

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

NewService creates and starts a service endpoint.

NewServiceTCP

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

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

Methods

Broadcast

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

Broadcast sends an event to all connected clients.

Call

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.

Close

func (s *Service) Close() error

Close stops the service listener and all client connections.

GetClientUID

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

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

Handle

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

Handle registers a method handler for an event.

HandleFunc

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

HandleFunc registers a simple handler that returns a fixed response.

IsRunning

func (s *Service) IsRunning() bool

IsRunning returns true if the service is running.

OnDisconnect

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

OnDisconnect sets the disconnection callback.

Run

func (s *Service) Run()

Run blocks until the service is closed.

Send

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

DecodeTransaction

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

DecodeTransaction decodes a transaction from a byte slice

NewTransaction

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

NewTransaction creates a new transaction

ReadTransaction

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

ReadTransaction reads a transaction from an io.Reader

Methods

Encode

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

Encode writes the transaction to a byte slice

Error

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

Error creates an error reply

PayloadString

func (t *Transaction) PayloadString() string

PayloadString returns payload as string

PayloadUint32

func (t *Transaction) PayloadUint32() uint32

PayloadUint32 returns first 4 bytes of payload as uint32

Reply

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

Reply creates a reply transaction to this one

Size

func (t *Transaction) Size() uint16

Size returns the payload size

TotalSize

func (t *Transaction) TotalSize() int

TotalSize returns the total transaction size including header

WriteTo

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

WriteTo writes the transaction to an io.Writer