sutra

package
v0.0.0-...-7e1b392 Latest Latest
Warning

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

 Go to latest Published: Feb 14, 2026 License: GPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source 
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.

View Source 
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.

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

DefaultSocketPath is the legacy default Sutra socket path.

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

HeaderSize is the size of the transaction header in bytes

View Source 
const MaxPayloadSize = 65535

MaxPayloadSize is the maximum payload size

Variables

This section is empty.

Functions

func DecodeString 

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

DecodeString decodes a length-prefixed string

func EncodeString 

func EncodeString(s string) []byte

EncodeString encodes a string with length prefix

func EncodeUint32 

func EncodeUint32(v uint32) []byte

EncodeUint32 encodes a uint32 as payload bytes

Types

type Client 

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

Client represents a connection to a service endpoint.

func Connect 

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

Connect connects to a service endpoint socket.

func (*Client) Broadcast 

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

Broadcast sends a broadcast transaction handled by the target service.

func (*Client) 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.

func (*Client) Close 

func (c *Client) Close() error

Close closes the client connection.

func (*Client) IsConnected 

func (c *Client) IsConnected() bool

IsConnected returns true if the client is connected.

func (*Client) Lookup 

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

Lookup is unsupported in decentralized mode.

func (*Client) Off 

func (c *Client) Off(event uint16)

Off removes an event handler.

func (*Client) On 

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

On registers an event handler.

func (*Client) OnDisconnect 

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

OnDisconnect sets the disconnection callback.

func (*Client) Ping 

func (c *Client) Ping() error

Ping is unsupported in decentralized mode.

func (*Client) Send 

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

Send sends a transaction without waiting for response.

type 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.

func NewDecoder 

func NewDecoder(data []byte) *Decoder

NewDecoder creates a decoder over the given byte slice.

func (*Decoder) Bool 

func (d *Decoder) Bool() bool

func (*Decoder) Bytes 

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

func (*Decoder) Err 

func (d *Decoder) Err() error

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

func (*Decoder) Int 

func (d *Decoder) Int() int

func (*Decoder) Int32 

func (d *Decoder) Int32() int32

func (*Decoder) Rune 

func (d *Decoder) Rune() rune

func (*Decoder) String 

func (d *Decoder) String() string

func (*Decoder) Uint8 

func (d *Decoder) Uint8() uint8

func (*Decoder) Uint16 

func (d *Decoder) Uint16() uint16

func (*Decoder) Uint32 

func (d *Decoder) Uint32() uint32

func (*Decoder) Uint64 

func (d *Decoder) Uint64() uint64

type 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).

func NewEncoder 

func NewEncoder(capacity int) *Encoder

NewEncoder creates an encoder with the given initial capacity hint.

func (*Encoder) Bytes 

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

Bytes returns the encoded buffer.

func (*Encoder) PutBool 

func (e *Encoder) PutBool(v bool)

func (*Encoder) PutBytes 

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

func (*Encoder) PutInt 

func (e *Encoder) PutInt(v int)

func (*Encoder) PutInt32 

func (e *Encoder) PutInt32(v int32)

func (*Encoder) PutRune 

func (e *Encoder) PutRune(v rune)

func (*Encoder) PutString 

func (e *Encoder) PutString(v string)

func (*Encoder) PutUint8 

func (e *Encoder) PutUint8(v uint8)

func (*Encoder) PutUint16 

func (e *Encoder) PutUint16(v uint16)

func (*Encoder) PutUint32 

func (e *Encoder) PutUint32(v uint32)

func (*Encoder) PutUint64 

func (e *Encoder) PutUint64(v uint64)

type EventHandler 

type EventHandler func(t *Transaction)

EventHandler handles incoming events.

type MethodHandler 

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

MethodHandler handles a method call and returns a response.

type Service 

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

Service represents a decentralized named service endpoint.

func NewService 

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

NewService creates and starts a service endpoint.

func (*Service) Broadcast 

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

Broadcast sends an event to all connected clients.

func (*Service) 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.

func (*Service) Close 

func (s *Service) Close() error

Close stops the service listener and all client connections.

func (*Service) Handle 

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

Handle registers a method handler for an event.

func (*Service) HandleFunc 

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

HandleFunc registers a simple handler that returns a fixed response.

func (*Service) IsRunning 

func (s *Service) IsRunning() bool

IsRunning returns true if the service is running.

func (*Service) OnDisconnect 

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

OnDisconnect sets the disconnection callback.

func (*Service) Run 

func (s *Service) Run()

Run blocks until the service is closed.

func (*Service) Send 

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

Send sends a message to a destination client.

type 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]

func DecodeTransaction 

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

DecodeTransaction decodes a transaction from a byte slice

func NewTransaction 

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

NewTransaction creates a new transaction

func ReadTransaction 

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

ReadTransaction reads a transaction from an io.Reader

func (*Transaction) Encode 

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

Encode writes the transaction to a byte slice

func (*Transaction) Error 

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

Error creates an error reply

func (*Transaction) PayloadString 

func (t *Transaction) PayloadString() string

PayloadString returns payload as string

func (*Transaction) PayloadUint32 

func (t *Transaction) PayloadUint32() uint32

PayloadUint32 returns first 4 bytes of payload as uint32

func (*Transaction) Reply 

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

Reply creates a reply transaction to this one

func (*Transaction) Size 

func (t *Transaction) Size() uint16

Size returns the payload size

func (*Transaction) TotalSize 

func (t *Transaction) TotalSize() int

TotalSize returns the total transaction size including header

func (*Transaction) WriteTo 

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

WriteTo writes the transaction to an io.Writer

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.