application

package
v0.2.20 Latest Latest
Warning

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

 Go to latest Published: Sep 8, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package application is the handwritten Go contract for proto/cloudpath/v1/application.proto (Application Protocol v1).

ApplicationEffect is deliberately a closed set: upsert/delete domain records, request commands, schedule/cancel tasks and send notifications. It cannot carry arbitrary SQL, shell commands, file operations or global credential requests. Plugin HTTP requests get tenant/actor/instance/scope context injected by Core and are scoped to /api/plugins/{plugin_id}/instances/{instance_id}/....

Index

Constants

View Source 
const (
	MethodInitialize        = "cloudpath.v1.application.ApplicationService/Initialize"
	MethodDescribe          = "cloudpath.v1.application.ApplicationService/Describe"
	MethodConfigureInstance = "cloudpath.v1.application.ApplicationService/ConfigureInstance"
	MethodValidateBinding   = "cloudpath.v1.application.ApplicationService/ValidateBinding"
	MethodHandleEvents      = "cloudpath.v1.application.ApplicationService/HandleEvents"
	MethodHandleRequest     = "cloudpath.v1.application.ApplicationService/HandleRequest"
	MethodRunJob            = "cloudpath.v1.application.ApplicationService/RunJob"
	MethodHealth            = "cloudpath.v1.application.ApplicationService/Health"
	MethodShutdown          = "cloudpath.v1.application.ApplicationService/Shutdown"
)

Service method names carried on the wire.

View Source 
const PropertyObservedEvent = "cloudpath.dev/event/property-observed@1"

PropertyObservedEvent delivers one model.Observation as PayloadJSON. The host routes only declared properties of a bound entity in the same tenant. It is a sampled fact, not proof of a physical user action or a completed command.

View Source 
const ProtocolVersion uint32 = 1

ProtocolVersion is the single application protocol version implemented here.

View Source 
const SchemaVersion = "1"

SchemaVersion is the data semantic version stamped on event/effect messages.

Variables

This section is empty.

Functions

func NewRPCServer 

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

NewRPCServer binds impl to a transport and returns the dispatcher.

Types

type ApplicationClient 

type ApplicationClient interface {
	Initialize(ctx context.Context, req *InitializeRequest) (*InitializeResponse, error)
	Describe(ctx context.Context) (*ApplicationDescriptor, error)
	ConfigureInstance(ctx context.Context, req *ConfigureInstanceRequest) (*ConfigureInstanceResponse, error)
	ValidateBinding(ctx context.Context, req *ValidateBindingRequest) (*ValidateBindingResponse, error)
	HandleEvents(ctx context.Context) (ApplicationEventStream, error)
	HandleRequest(ctx context.Context, req *PluginHTTPRequest) (*PluginHTTPResponse, error)
	RunJob(ctx context.Context, req *RunJobRequest) (*RunJobResponse, error)
	Health(ctx context.Context) (*HealthResponse, error)
	Shutdown(ctx context.Context, req *ShutdownRequest) (*ShutdownResponse, error)
}

ApplicationClient is the Core-side view of ApplicationService.

func NewClient 

func NewClient(tr transport.Transport) ApplicationClient

NewClient wraps a transport as an ApplicationClient.

type ApplicationDescriptor 

type ApplicationDescriptor struct {
	ApplicationID   string                  `json:"application_id"`
	Version         string                  `json:"version"`
	SchemaVersions  []string                `json:"schema_versions"`
	Requirements    []RequirementDescriptor `json:"requirements"`
	Jobs            []JobDescriptor         `json:"jobs"`
	DeclarativeOnly bool                    `json:"declarative_only"`
}

type ApplicationEffect 

type ApplicationEffect struct {
	PluginInstanceID string                 `json:"plugin_instance_id"`
	Sequence         uint64                 `json:"sequence"`
	SchemaVersion    string                 `json:"schema_version"`
	Union            ApplicationEffectUnion `json:"-"`
}

func (*ApplicationEffect) MarshalJSON 

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

MarshalJSON implements the ApplicationEffect oneof.

func (*ApplicationEffect) UnmarshalJSON 

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

UnmarshalJSON implements the ApplicationEffect oneof.

type ApplicationEffectUnion 

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

type ApplicationEffectWriter 

type ApplicationEffectWriter interface {
	Send(ctx context.Context, effect *ApplicationEffect) error
}

ApplicationEffectWriter lets a plugin emit effects.

type ApplicationEvent 

type ApplicationEvent struct {
	PluginInstanceID string                `json:"plugin_instance_id"`
	Sequence         uint64                `json:"sequence"`
	SchemaVersion    string                `json:"schema_version"`
	Union            ApplicationEventUnion `json:"-"`
}

func (*ApplicationEvent) MarshalJSON 

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

MarshalJSON implements the ApplicationEvent oneof.

func (*ApplicationEvent) UnmarshalJSON 

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

UnmarshalJSON implements the ApplicationEvent oneof.

type ApplicationEventReader 

type ApplicationEventReader interface {
	Recv(ctx context.Context) (*ApplicationEvent, error)
}

ApplicationEventReader feeds events to a plugin handler.

type ApplicationEventStream 

type ApplicationEventStream interface {
	Send(ctx context.Context, event *ApplicationEvent) error
	CloseSend(ctx context.Context) error
	Recv(ctx context.Context) (*ApplicationEffect, error)
	Cancel(ctx context.Context) error
}

ApplicationEventStream is the client view of the HandleEvents bidi stream: Core sends events and receives effects.

type ApplicationEventUnion 

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

type ApplicationServer 

type ApplicationServer interface {
	Initialize(ctx context.Context, req *InitializeRequest) (*InitializeResponse, error)
	Describe(ctx context.Context) (*ApplicationDescriptor, error)
	ConfigureInstance(ctx context.Context, req *ConfigureInstanceRequest) (*ConfigureInstanceResponse, error)
	ValidateBinding(ctx context.Context, req *ValidateBindingRequest) (*ValidateBindingResponse, error)
	HandleEvents(ctx context.Context, events ApplicationEventReader, effects ApplicationEffectWriter) error
	HandleRequest(ctx context.Context, req *PluginHTTPRequest) (*PluginHTTPResponse, error)
	RunJob(ctx context.Context, req *RunJobRequest) (*RunJobResponse, error)
	Health(ctx context.Context) (*HealthResponse, error)
	Shutdown(ctx context.Context, req *ShutdownRequest) (*ShutdownResponse, error)
}

ApplicationServer is the plugin-side implementation of ApplicationService.

type Binding 

type Binding struct {
	RequirementID string `json:"requirement_id"`
	EntityID      string `json:"entity_id"`
}

type BindingIssue 

type BindingIssue struct {
	RequirementID string `json:"requirement_id"`
	Severity      string `json:"severity"`
	Message       string `json:"message"`
}

type CancelScheduledTask 

type CancelScheduledTask struct {
	ScheduleID string `json:"schedule_id"`
}

type CapabilityEvent 

type CapabilityEvent struct {
	RequirementID string `json:"requirement_id"`
	EntityID      string `json:"entity_id"`
	EventType     string `json:"event_type"`
	PayloadJSON   string `json:"payload_json"`
	OccurredAt    string `json:"occurred_at"`
}

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 name for the command 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 DeleteDomainRecord 

type DeleteDomainRecord struct {
	RecordType string `json:"record_type"`
	RecordID   string `json:"record_id"`
	Version    string `json:"version"`
}

type DescribeRequest 

type DescribeRequest struct{}

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"`
	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 InstanceLifecycle 

type InstanceLifecycle struct {
	State  string `json:"state"`
	Detail string `json:"detail"`
}

type JobDescriptor 

type JobDescriptor struct {
	ID              string `json:"id"`
	Title           string `json:"title"`
	InputSchemaJSON string `json:"input_schema_json"`
	// ManualOnly jobs are operator actions, never automatic minute-loop work.
	ManualOnly bool `json:"manual_only,omitempty"`
}

type PluginHTTPRequest 

type PluginHTTPRequest struct {
	RequestID        string            `json:"request_id"`
	PluginInstanceID string            `json:"plugin_instance_id"`
	Method           string            `json:"method"`
	Path             string            `json:"path"`
	Headers          map[string]string `json:"headers"`
	Body             []byte            `json:"body"`
	Context          RequestContext    `json:"context"`
}

type PluginHTTPResponse 

type PluginHTTPResponse struct {
	StatusCode uint32            `json:"status_code"`
	Headers    map[string]string `json:"headers"`
	Body       []byte            `json:"body"`
}

type RequestCommand 

type RequestCommand struct {
	EntityID       string `json:"entity_id"`
	Action         string `json:"action"`
	ArgsJSON       string `json:"args_json"`
	IdempotencyKey string `json:"idempotency_key"`
	Deadline       string `json:"deadline"`
}

type RequestCompleted 

type RequestCompleted struct {
	RequestID  string       `json:"request_id"`
	EntityID   string       `json:"entity_id"`
	Action     string       `json:"action"`
	State      CommandState `json:"state"`
	ResultJSON string       `json:"result_json"`
	ErrorCode  string       `json:"error_code"`
}

type RequestContext 

type RequestContext struct {
	TenantID   string   `json:"tenant_id"`
	ActorID    string   `json:"actor_id"`
	InstanceID string   `json:"instance_id"`
	Scopes     []string `json:"scopes"`
}

type RequirementDescriptor 

type RequirementDescriptor struct {
	ID          string `json:"id"`
	Capability  string `json:"capability"`
	Cardinality string `json:"cardinality"`
	MinItems    uint32 `json:"min_items"`
}

type RunJobRequest 

type RunJobRequest struct {
	PluginInstanceID string `json:"plugin_instance_id"`
	JobID            string `json:"job_id"`
	JobType          string `json:"job_type"`
	ArgsJSON         string `json:"args_json"`
	IdempotencyKey   string `json:"idempotency_key"`
	Deadline         string `json:"deadline"`
}

type RunJobResponse 

type RunJobResponse struct {
	JobID      string  `json:"job_id"`
	Status     *Status `json:"status"`
	ResultJSON string  `json:"result_json"`
}

type ScheduleTask 

type ScheduleTask struct {
	ScheduleID  string `json:"schedule_id"`
	Cron        string `json:"cron"`
	PayloadJSON string `json:"payload_json"`
}

type ScheduleTick 

type ScheduleTick struct {
	ScheduleID string `json:"schedule_id"`
	OccurredAt string `json:"occurred_at"`
	WindowJSON string `json:"window_json"`
}

type SendNotification 

type SendNotification struct {
	Title    string `json:"title"`
	Body     string `json:"body"`
	Severity string `json:"severity"`
}

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 mirrors the inline Status message in application.proto and shares the driver protocol's code table.

type UpsertDomainRecord 

type UpsertDomainRecord struct {
	RecordType string `json:"record_type"`
	RecordID   string `json:"record_id"`
	DataJSON   string `json:"data_json"`
	Version    string `json:"version"`
}

type ValidateBindingRequest 

type ValidateBindingRequest struct {
	PluginInstanceID string    `json:"plugin_instance_id"`
	Bindings         []Binding `json:"bindings"`
}

type ValidateBindingResponse 

type ValidateBindingResponse struct {
	Valid  bool           `json:"valid"`
	Issues []BindingIssue `json:"issues"`
}

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.