driver

package
v0.2.43 Latest Latest
Warning

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

 Go to latest Published: Sep 10, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package driver is the handwritten Go contract for proto/cloudpath/v1/driver.proto (Driver Protocol v1).

Every type maps 1:1 to a proto message and is JSON-encoded exactly the way the proto text defines it (proto3 json_name, snake_case keys, bytes as base64). oneof fields are modeled as a typed Union plus custom MarshalJSON/UnmarshalJSON in codec.go. There is no protoc-generated code, and no third-party dependency is used.

The package also provides DriverClient/DriverServer interfaces and in-process adapters that run the protocol over sdk/go/transport: 

cli := driver.NewClient(transportEnd)
srv := driver.NewRPCServer(transportEnd, myDriverImpl)
go srv.Serve(ctx)

See testing/plugin-harness for a mock Core, mock Driver and the conformance suite.

Index

Constants

View Source 
const (
	MethodInitialize        = "cloudpath.v1.driver.DriverService/Initialize"
	MethodDescribe          = "cloudpath.v1.driver.DriverService/Describe"
	MethodConfigureInstance = "cloudpath.v1.driver.DriverService/ConfigureInstance"
	MethodDiscover          = "cloudpath.v1.driver.DriverService/Discover"
	MethodOpenDevice        = "cloudpath.v1.driver.DriverService/OpenDevice"
	MethodCloseDevice       = "cloudpath.v1.driver.DriverService/CloseDevice"
	MethodWatch             = "cloudpath.v1.driver.DriverService/Watch"
	MethodExecute           = "cloudpath.v1.driver.DriverService/Execute"
	MethodHealth            = "cloudpath.v1.driver.DriverService/Health"
	MethodShutdown          = "cloudpath.v1.driver.DriverService/Shutdown"
)

Service method names carried on the wire.

View Source 
const ProtocolVersion uint32 = 1

ProtocolVersion is the single driver protocol version implemented here.

View Source 
const SchemaVersion = "1"

SchemaVersion is the data semantic version stamped on every stream message.

Variables

This section is empty.

Functions

func NegotiateProtocolVersion 

func NegotiateProtocolVersion(supported []uint32, prefer uint32, minSupported, maxSupported uint32) (uint32, bool)

NegotiateProtocolVersion picks the highest version that is supported by both sides and lies inside [minSupported, maxSupported]. It returns (0, false) when the sets are disjoint. prefer is the caller's preferred version and breaks ties when both sides support multiple versions.

func NewRPCServer 

func NewRPCServer(tr transport.Transport, impl DriverServer) *rpc.Server

NewRPCServer binds impl to a transport and returns the dispatcher. Call Serve to consume frames.

func ValidateDriverMessage 

func ValidateDriverMessage(m *DriverMessage) error

ValidateDriverMessage checks the report envelope invariants that every implementation must enforce before sending: instance ID, positive sequence, schema version and a body. It returns a descriptive error.

Types

type ActionDescriptor 

type ActionDescriptor struct {
	Name             string `json:"name"`
	InputSchemaJSON  string `json:"input_schema_json"`
	ResultSchemaJSON string `json:"result_schema_json"`
	// Optional Capability metadata; omitted values preserve legacy descriptors.
	Title        string `json:"title,omitempty"`
	Description  string `json:"description,omitempty"`
	Destructive  bool   `json:"destructive,omitempty"`
	Confirmation string `json:"confirmation,omitempty"`
}

type CapabilityDescriptor 

type CapabilityDescriptor struct {
	ID         string               `json:"id"`
	Title      string               `json:"title"`
	Properties []PropertyDescriptor `json:"properties"`
	Events     []EventDescriptor    `json:"events"`
	Actions    []ActionDescriptor   `json:"actions"`
}

type CloseDeviceRequest 

type CloseDeviceRequest struct {
	PluginInstanceID string `json:"plugin_instance_id"`
	DeviceID         string `json:"device_id"`
}

type CloseDeviceResponse 

type CloseDeviceResponse struct {
	PluginInstanceID string  `json:"plugin_instance_id"`
	DeviceID         string  `json:"device_id"`
	Status           *Status `json:"status"`
}

type CommandProgress 

type CommandProgress struct {
	CommandID      string       `json:"command_id"`
	IdempotencyKey string       `json:"idempotency_key"`
	EntityID       string       `json:"entity_id"`
	Action         string       `json:"action"`
	State          CommandState `json:"state"`
	Progress       float64      `json:"progress"`
	Detail         string       `json:"detail"`
	ResultJSON     string       `json:"result_json"`
	ErrorCode      string       `json:"error_code"`
}

type CommandState 

type CommandState int32
const (
	CommandStateUnspecified CommandState = 0
	CommandStateCreated     CommandState = 1
	CommandStateDispatched  CommandState = 2
	CommandStateAccepted    CommandState = 3
	CommandStateRunning     CommandState = 4
	CommandStateSucceeded   CommandState = 5
	CommandStateFailed      CommandState = 6
	CommandStateTimedOut    CommandState = 7
	CommandStateCancelled   CommandState = 8
)

func (CommandState) String 

func (s CommandState) String() string

String returns a stable, human-readable name for the state.

type ConfigureInstanceRequest 

type ConfigureInstanceRequest struct {
	PluginInstanceID string `json:"plugin_instance_id"`
	Config           []byte `json:"config"`
	ConfigRevision   uint32 `json:"config_revision"`
}

type ConfigureInstanceResponse 

type ConfigureInstanceResponse struct {
	PluginInstanceID string  `json:"plugin_instance_id"`
	AppliedRevision  uint32  `json:"applied_revision"`
	Status           *Status `json:"status"`
}

type DescribeRequest 

type DescribeRequest struct{}

DescribeRequest is empty by contract; the descriptor must be stable and deterministic for a given plugin version.

type Device 

type Device struct {
	DeviceID     string       `json:"device_id"`
	ExternalID   string       `json:"external_id"`
	Manufacturer string       `json:"manufacturer"`
	Model        string       `json:"model"`
	Status       DeviceStatus `json:"status"`
	DisplayName  string       `json:"display_name"`
}

type DeviceStatus 

type DeviceStatus int32
const (
	DeviceStatusUnspecified DeviceStatus = 0
	DeviceStatusOnline      DeviceStatus = 1
	DeviceStatusOffline     DeviceStatus = 2
	DeviceStatusUnavailable DeviceStatus = 3
	DeviceStatusDegraded    DeviceStatus = 4
)

func (DeviceStatus) String 

func (s DeviceStatus) String() string

String returns a stable, human-readable name for the device status.

type DeviceUpsert 

type DeviceUpsert struct {
	Device  Device `json:"device"`
	Removed bool   `json:"removed"`
}

type Diagnostic 

type Diagnostic struct {
	Level      string            `json:"level"`
	Message    string            `json:"message"`
	Fields     map[string]string `json:"fields"`
	ObservedAt string            `json:"observed_at"`
	RawJSON    string            `json:"raw_json"`
}

type DiscoverRequest 

type DiscoverRequest struct {
	PluginInstanceID string            `json:"plugin_instance_id"`
	DiscoveryID      string            `json:"discovery_id"`
	Parameters       map[string]string `json:"parameters"`
}

type DiscoveryEvent 

type DiscoveryEvent struct {
	PluginInstanceID string              `json:"plugin_instance_id"`
	Sequence         uint64              `json:"sequence"`
	SchemaVersion    string              `json:"schema_version"`
	DiscoveryID      string              `json:"discovery_id"`
	Union            DiscoveryEventUnion `json:"-"`
}

DiscoveryEvent carries exactly one body variant.

func (*DiscoveryEvent) MarshalJSON 

func (e *DiscoveryEvent) MarshalJSON() ([]byte, error)

MarshalJSON implements the DiscoveryEvent oneof.

func (*DiscoveryEvent) UnmarshalJSON 

func (e *DiscoveryEvent) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the DiscoveryEvent oneof.

type DiscoveryEventUnion 

type DiscoveryEventUnion interface {
	// contains filtered or unexported methods
}

type DiscoveryFailed 

type DiscoveryFailed struct {
	Status *Status `json:"status"`
}

type DiscoveryFinished 

type DiscoveryFinished struct {
	FoundCount uint32 `json:"found_count"`
}

type DiscoveryFoundDevice 

type DiscoveryFoundDevice struct {
	DeviceID     string `json:"device_id"`
	ExternalID   string `json:"external_id"`
	Manufacturer string `json:"manufacturer"`
	Model        string `json:"model"`
}

type DiscoveryProgress 

type DiscoveryProgress struct {
	Fraction float64 `json:"fraction"`
	Detail   string  `json:"detail"`
}

type DiscoveryStarted 

type DiscoveryStarted struct {
	DiscoveryID string `json:"discovery_id"`
}

type DiscoveryStream 

type DiscoveryStream interface {
	Recv(ctx context.Context) (*DiscoveryEvent, error)
	Cancel(ctx context.Context) error
}

DiscoveryStream is the client view of the Discover server stream.

type DiscoveryWriter 

type DiscoveryWriter interface {
	Send(ctx context.Context, msg *DiscoveryEvent) error
}

DiscoveryWriter lets a plugin publish discovery events.

type DriverClient 

type DriverClient interface {
	Initialize(ctx context.Context, req *InitializeRequest) (*InitializeResponse, error)
	Describe(ctx context.Context) (*DriverDescriptor, error)
	ConfigureInstance(ctx context.Context, req *ConfigureInstanceRequest) (*ConfigureInstanceResponse, error)
	Discover(ctx context.Context, req *DiscoverRequest) (DiscoveryStream, error)
	OpenDevice(ctx context.Context, req *OpenDeviceRequest) (*OpenDeviceResponse, error)
	CloseDevice(ctx context.Context, req *CloseDeviceRequest) (*CloseDeviceResponse, error)
	Watch(ctx context.Context, req *WatchRequest) (DriverMessageStream, error)
	Execute(ctx context.Context, req *ExecuteRequest) (*ExecuteResponse, error)
	Health(ctx context.Context) (*HealthResponse, error)
	Shutdown(ctx context.Context, req *ShutdownRequest) (*ShutdownResponse, error)
}

DriverClient is the Core-side view of DriverService.

func NewClient 

func NewClient(tr transport.Transport) DriverClient

NewClient wraps a transport as a DriverClient.

type DriverDescriptor 

type DriverDescriptor struct {
	DriverID       string                 `json:"driver_id"`
	Version        string                 `json:"version"`
	SchemaVersions []string               `json:"schema_versions"`
	Capabilities   []CapabilityDescriptor `json:"capabilities"`
}

type DriverMessage 

type DriverMessage struct {
	PluginInstanceID string             `json:"plugin_instance_id"`
	Sequence         uint64             `json:"sequence"`
	SchemaVersion    string             `json:"schema_version"`
	DeviceID         string             `json:"device_id"`
	Union            DriverMessageUnion `json:"-"`
}

DriverMessage is the single report envelope of the Watch stream. Every message carries plugin_instance_id, a monotonically increasing sequence scoped to (instance, device), and a schema version. Core dedupes on that scope; see SequenceTracker.

func SortMessagesBySequence 

func SortMessagesBySequence(msgs []*DriverMessage) []*DriverMessage

SortMessagesBySequence is a helper for replay buffers: it returns a copy sorted ascending by sequence (stable) without mutating the input.

func (*DriverMessage) MarshalJSON 

func (m *DriverMessage) MarshalJSON() ([]byte, error)

MarshalJSON implements the DriverMessage oneof.

func (*DriverMessage) UnmarshalJSON 

func (m *DriverMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the DriverMessage oneof and rejects messages with zero or multiple bodies.

type DriverMessageStream 

type DriverMessageStream interface {
	Recv(ctx context.Context) (*DriverMessage, error)
	Cancel(ctx context.Context) error
}

DriverMessageStream is the client view of the Watch server stream.

type DriverMessageUnion 

type DriverMessageUnion interface {
	// contains filtered or unexported methods
}

type DriverMessageWriter 

type DriverMessageWriter interface {
	Send(ctx context.Context, msg *DriverMessage) error
}

DriverMessageWriter lets a plugin publish Watch messages.

type DriverServer 

type DriverServer interface {
	Initialize(ctx context.Context, req *InitializeRequest) (*InitializeResponse, error)
	Describe(ctx context.Context) (*DriverDescriptor, error)
	ConfigureInstance(ctx context.Context, req *ConfigureInstanceRequest) (*ConfigureInstanceResponse, error)
	Discover(ctx context.Context, req *DiscoverRequest, stream DiscoveryWriter) error
	OpenDevice(ctx context.Context, req *OpenDeviceRequest) (*OpenDeviceResponse, error)
	CloseDevice(ctx context.Context, req *CloseDeviceRequest) (*CloseDeviceResponse, error)
	Watch(ctx context.Context, req *WatchRequest, stream DriverMessageWriter) error
	Execute(ctx context.Context, req *ExecuteRequest) (*ExecuteResponse, error)
	Health(ctx context.Context) (*HealthResponse, error)
	Shutdown(ctx context.Context, req *ShutdownRequest) (*ShutdownResponse, error)
}

DriverServer is the plugin-side implementation of DriverService.

type Entity 

type Entity struct {
	EntityID     string            `json:"entity_id"`
	DeviceID     string            `json:"device_id"`
	UniqueKey    string            `json:"unique_key"`
	Name         string            `json:"name"`
	Category     EntityCategory    `json:"category"`
	Capabilities []string          `json:"capabilities"`
	Attributes   map[string]string `json:"attributes"`
}

type EntityCategory 

type EntityCategory int32
const (
	EntityCategoryUnspecified EntityCategory = 0
	EntityCategorySensor      EntityCategory = 1
	EntityCategoryActuator    EntityCategory = 2
	EntityCategoryDiagnostic  EntityCategory = 3
	EntityCategoryConfig      EntityCategory = 4
)

type EntityUpsert 

type EntityUpsert struct {
	Entity  Entity `json:"entity"`
	Removed bool   `json:"removed"`
}

type Event 

type Event struct {
	EntityID      string `json:"entity_id"`
	DeviceID      string `json:"device_id"`
	EventType     string `json:"event_type"`
	PayloadJSON   string `json:"payload_json"`
	OccurredAt    string `json:"occurred_at"`
	CorrelationID string `json:"correlation_id"`
}

type EventDescriptor 

type EventDescriptor struct {
	Name              string `json:"name"`
	PayloadSchemaJSON string `json:"payload_schema_json"`
}

type ExecuteRequest 

type ExecuteRequest struct {
	PluginInstanceID string `json:"plugin_instance_id"`
	DeviceID         string `json:"device_id,omitempty"`
	IdempotencyKey   string `json:"idempotency_key"`
	EntityID         string `json:"entity_id"`
	Action           string `json:"action"`
	ArgsJSON         string `json:"args_json"`
	Deadline         string `json:"deadline"`
	Actor            string `json:"actor"`
	CancelCommandID  string `json:"cancel_command_id"`
}

ExecuteRequest either runs a command or, when CancelCommandID is non-empty, cancels the referenced in-flight command. IdempotencyKey is required in both cases so Core can safely retry.

type ExecuteResponse 

type ExecuteResponse struct {
	CommandID        string       `json:"command_id"`
	IdempotencyKey   string       `json:"idempotency_key"`
	Status           *Status      `json:"status"`
	State            CommandState `json:"state"`
	Replay           bool         `json:"replay"`
	AcceptedDeadline string       `json:"accepted_deadline"`
}

type HealthRequest 

type HealthRequest struct{}

type HealthResponse 

type HealthResponse struct {
	State     HealthState      `json:"state"`
	Instances []InstanceHealth `json:"instances"`
}

type HealthState 

type HealthState int32
const (
	HealthStateUnspecified HealthState = 0
	HealthStateServing     HealthState = 1
	HealthStateNotServing  HealthState = 2
)

type InitializeRequest 

type InitializeRequest struct {
	PluginID                  string            `json:"plugin_id"`
	PluginVersion             string            `json:"plugin_version"`
	LaunchID                  string            `json:"launch_id"`
	HandshakeCookie           string            `json:"handshake_cookie"`
	ProtocolVersion           uint32            `json:"protocol_version"`
	SupportedProtocolVersions []uint32          `json:"supported_protocol_versions"`
	NodeID                    string            `json:"node_id"`
	RuntimeType               string            `json:"runtime_type"`
	HostInfo                  map[string]string `json:"host_info"`
}

type InitializeResponse 

type InitializeResponse struct {
	NegotiatedProtocolVersion uint32  `json:"negotiated_protocol_version"`
	Status                    *Status `json:"status"`
	ReplaySupported           bool    `json:"replay_supported"`
	RuntimeID                 string  `json:"runtime_id"`
}

type InstanceHealth 

type InstanceHealth struct {
	PluginInstanceID string      `json:"plugin_instance_id"`
	State            HealthState `json:"state"`
	Detail           string      `json:"detail"`
}

type Observation 

type Observation struct {
	EntityID   string `json:"entity_id"`
	Capability string `json:"capability"`
	Property   string `json:"property"`
	Value      Value  `json:"value"`
	ObservedAt string `json:"observed_at"`
	ReceivedAt string `json:"received_at"`
	Quality    string `json:"quality"`
}

type OpenDeviceRequest 

type OpenDeviceRequest struct {
	PluginInstanceID string            `json:"plugin_instance_id"`
	DeviceID         string            `json:"device_id"`
	ConnectionHints  map[string]string `json:"connection_hints"`
}

type OpenDeviceResponse 

type OpenDeviceResponse struct {
	PluginInstanceID string  `json:"plugin_instance_id"`
	DeviceID         string  `json:"device_id"`
	Status           *Status `json:"status"`
}

type PropertyDescriptor 

type PropertyDescriptor struct {
	Name    string   `json:"name"`
	Type    string   `json:"type"`
	Unit    string   `json:"unit"`
	Access  string   `json:"access"`
	Quality []string `json:"quality"`
}

type SequenceTracker 

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

SequenceTracker implements Core-side deduplication: for a given (plugin_instance_id, device_id) scope only a sequence strictly greater than the last accepted one is admitted. Duplicates and stale/out-of-order frames are therefore dropped at the boundary.

func NewSequenceTracker 

func NewSequenceTracker() *SequenceTracker

NewSequenceTracker returns an empty tracker.

func (*SequenceTracker) Accept 

func (t *SequenceTracker) Accept(instanceID, deviceID string, sequence uint64) bool

Accept reports whether sequence is new for the scope and, when it is, records it. Sequence 0 is rejected because protocol messages must carry a positive sequence.

func (*SequenceTracker) AcceptMessage 

func (t *SequenceTracker) AcceptMessage(m *DriverMessage) bool

AcceptMessage applies Accept to a DriverMessage's own scope fields.

func (*SequenceTracker) Count 

func (t *SequenceTracker) Count() int

Count returns how many distinct scopes have been observed.

func (*SequenceTracker) Last 

func (t *SequenceTracker) Last(instanceID, deviceID string) uint64

Last returns the highest accepted sequence for the scope (0 if none).

func (*SequenceTracker) Reset 

func (t *SequenceTracker) Reset()

Reset clears all scopes. Useful when a plugin restarts and replays from a fresh sequence space.

type ShutdownRequest 

type ShutdownRequest struct {
	Reason       string `json:"reason"`
	GraceSeconds uint32 `json:"grace_seconds"`
}

type ShutdownResponse 

type ShutdownResponse struct {
	Status *Status `json:"status"`
}

type Status 

type Status = status.Status

Status is the protocol status type (mirrors the inline Status message in driver.proto; the application protocol shares the same code table).

type Value 

type Value struct {
	Kind        ValueKind `json:"-"`
	NumberValue float64   `json:"-"`
	IntValue    int64     `json:"-"`
	StringValue string    `json:"-"`
	BoolValue   bool      `json:"-"`
	JSONValue   string    `json:"-"`
}

Value is the typed oneof inside Observation.

func (*Value) MarshalJSON 

func (v *Value) MarshalJSON() ([]byte, error)

MarshalJSON implements the Value oneof.

func (*Value) UnmarshalJSON 

func (v *Value) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the Value oneof.

type ValueKind 

type ValueKind int32

ValueKind enumerates the Observation.Value oneof alternatives. 

const (
	ValueUnspecified ValueKind = 0
	ValueNumber      ValueKind = 1
	ValueInt         ValueKind = 2
	ValueString      ValueKind = 3
	ValueBool        ValueKind = 4
	ValueJSON        ValueKind = 5
)

type WatchRequest 

type WatchRequest struct {
	PluginInstanceID   string   `json:"plugin_instance_id"`
	ResumeFromSequence uint64   `json:"resume_from_sequence"`
	DeviceIDs          []string `json:"device_ids"`
	MaxBuffered        uint32   `json:"max_buffered"`
}

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.