Developer SDK

Go examples

Install the SDK · View source on GitHub ↗

messages/subprotocol/device.go

go
package subprotocol

import (
	"errors"
	"slices"
	"sync/atomic"
	"time"

	sdk "github.com/urnetwork/sdk/v2026"
)

// The Device subprotocol methods this example uses, with the signatures that
// *sdk.DeviceLocal declares (sdk device_local_subprotocol.go). The tests drive
// an in-process stand-in through the same interface.
type Device interface {
	EnableSubprotocol(subprotocolId int32, listener sdk.SubprotocolListener) (sdk.Sub, error)
	SendSubprotocolBytes(subprotocolId int32, destinationClientId *sdk.Id, messageBytes []byte) bool
	QuerySubprotocols(destinationClientId *sdk.Id, timeoutMillis int64, callback sdk.SubprotocolsQueryCallback)
}

var _ Device = (*sdk.DeviceLocal)(nil)

var (
	ErrNotEnqueued = errors.New("the SDK did not enqueue the message")
	ErrNoAnswer    = errors.New("the peer did not answer the subprotocol query")
)

// Marshals one envelope and hands it to the device. nil means the SDK accepted
// the bytes for sending, not that the peer received them; only its Ack does.
// The device copies the bytes, so the caller keeps its slice.
func Send(device Device, destination *sdk.Id, envelope *Envelope) error {
	messageBytes, err := Marshal(envelope)
	if err != nil {
		return err
	}
	if !device.SendSubprotocolBytes(Id, destination, messageBytes) {
		return ErrNotEnqueued
	}
	return nil
}

// One message the listener copied: its source client and its own bytes. The
// Go SDK allocates the source id for each message, so it can be kept.
type Received struct {
	Source *sdk.Id
	Bytes  []byte
}

// The device listener of this subprotocol. SubprotocolMessage runs inline on
// the client's receive goroutine, and the bytes are borrowed until it returns,
// so it only bounds, copies and queues. Receive parses on the application's
// goroutine.
type Listener struct {
	Received chan Received
	// messages refused for their size or dropped because the queue was full
	Dropped atomic.Uint64
}

func NewListener(queueSize int) *Listener {
	return &Listener{Received: make(chan Received, queueSize)}
}

func (self *Listener) SubprotocolMessage(subprotocolId int32, sourceClientId *sdk.Id, messageBytes []byte) {
	if subprotocolId != Id || sourceClientId == nil || MaxMessageBytes < len(messageBytes) {
		self.Dropped.Add(1)
		return
	}
	select {
	case self.Received <- Received{Source: sourceClientId, Bytes: slices.Clone(messageBytes)}:
	default:
		// never block the receive path; the sender's Ack timeout covers the loss
		self.Dropped.Add(1)
	}
}

// Parses one queued message and acknowledges a valid note to its source. A
// message that does not parse is returned as an error and never acknowledged,
// and an Ack is never acknowledged.
func Receive(device Device, received Received) (*Envelope, error) {
	envelope, err := Parse(received.Bytes)
	if err != nil {
		return nil, err
	}
	if note := envelope.GetNote(); note != nil {
		if err := Send(device, received.Source, NewAck(note.GetMessageId())); err != nil {
			return envelope, err
		}
	}
	return envelope, nil
}

// Asks the peer which subprotocols it supports. true means it advertised this
// one, and false with a nil error means it answered without it. ErrNoAnswer
// means a timeout, a failed query or a peer older than the query, which says
// nothing about the peer.
func Supported(device Device, destination *sdk.Id, timeout time.Duration) (bool, error) {
	answers := make(queryCallback, 1)
	device.QuerySubprotocols(destination, timeout.Milliseconds(), answers)
	select {
	case answer := <-answers:
		if !answer.ok {
			return false, ErrNoAnswer
		}
		return answer.supported, nil
	case <-time.After(timeout + time.Second):
		return false, ErrNoAnswer
	}
}

type queryAnswer struct {
	supported bool
	ok        bool
}

// Receives the one answer to a query, which the SDK delivers from a worker.
type queryCallback chan queryAnswer

func (self queryCallback) Result(subprotocolIds *sdk.IntList, ok bool) {
	answer := queryAnswer{ok: ok}
	if ok && subprotocolIds != nil {
		answer.supported = subprotocolIds.Contains(Id)
	}
	select {
	case self <- answer:
	default:
	}
}