rpc

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: May 27, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

Package rpc carries the Twirp service implementation for Prism.

service.proto defines five RPCs (Plot, Validate, Scene, Plan, ListDatasets) under package prism.v1. Generated bindings live in service.pb.go + service.twirp.go (D083). PrismServer satisfies the generated Prism interface and reuses the same pipeline primitives the CLI calls: spec.DecodeBytes, plan/build.Build(Composite), plan.Execute, encode.Encode(Composite), the format's Renderer.

Selection-state synthesis is NOT part of the Twirp surface; that logic lives in the /prism/scene compatibility wrapper (D084) because Twirp envelopes do not carry per-call selection state.

Errors returned from every handler flow through ErrorInterceptor (interceptor.go / D085), which translates *errors.AppError and Pulse *CodedError to Twirp status codes by prefix.

Index

Constants

View Source
const PrismPathPrefix = "/twirp/prism.v1.Prism/"

PrismPathPrefix is a convenience constant that may identify URL paths. Should be used with caution, it only matches routes generated by Twirp Go clients, with the default "/twirp" prefix and default CamelCase service and method names. More info: https://twitchtv.github.io/twirp/docs/routing.html

Variables

View Source
var File_rpc_service_proto protoreflect.FileDescriptor

Functions

func ErrorInterceptor

func ErrorInterceptor(next twirp.Method) twirp.Method

ErrorInterceptor is a twirp.Interceptor that turns every non-Twirp error returned from a handler into a typed twirp.Error. twirp.Error values pass through unchanged.

func WriteError

func WriteError(resp http.ResponseWriter, err error)

WriteError writes an HTTP response with a valid Twirp error format (code, msg, meta). Useful outside of the Twirp server (e.g. http middleware), but does not trigger hooks. If err is not a twirp.Error, it will get wrapped with twirp.InternalErrorWith(err)

Types

type Dataset

type Dataset struct {
	Name   string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	Source string `protobuf:"bytes,2,opt,name=source,proto3" json:"source,omitempty"`
	// contains filtered or unexported fields
}

func (*Dataset) Descriptor deprecated

func (*Dataset) Descriptor() ([]byte, []int)

Deprecated: Use Dataset.ProtoReflect.Descriptor instead.

func (*Dataset) GetName

func (x *Dataset) GetName() string

func (*Dataset) GetSource

func (x *Dataset) GetSource() string

func (*Dataset) ProtoMessage

func (*Dataset) ProtoMessage()

func (*Dataset) ProtoReflect

func (x *Dataset) ProtoReflect() protoreflect.Message

func (*Dataset) Reset

func (x *Dataset) Reset()

func (*Dataset) String

func (x *Dataset) String() string

type DatasetsRequest

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

func (*DatasetsRequest) Descriptor deprecated

func (*DatasetsRequest) Descriptor() ([]byte, []int)

Deprecated: Use DatasetsRequest.ProtoReflect.Descriptor instead.

func (*DatasetsRequest) ProtoMessage

func (*DatasetsRequest) ProtoMessage()

func (*DatasetsRequest) ProtoReflect

func (x *DatasetsRequest) ProtoReflect() protoreflect.Message

func (*DatasetsRequest) Reset

func (x *DatasetsRequest) Reset()

func (*DatasetsRequest) String

func (x *DatasetsRequest) String() string

type DatasetsResponse

type DatasetsResponse struct {
	Datasets []*Dataset `protobuf:"bytes,1,rep,name=datasets,proto3" json:"datasets,omitempty"`
	// contains filtered or unexported fields
}

func (*DatasetsResponse) Descriptor deprecated

func (*DatasetsResponse) Descriptor() ([]byte, []int)

Deprecated: Use DatasetsResponse.ProtoReflect.Descriptor instead.

func (*DatasetsResponse) GetDatasets

func (x *DatasetsResponse) GetDatasets() []*Dataset

func (*DatasetsResponse) ProtoMessage

func (*DatasetsResponse) ProtoMessage()

func (*DatasetsResponse) ProtoReflect

func (x *DatasetsResponse) ProtoReflect() protoreflect.Message

func (*DatasetsResponse) Reset

func (x *DatasetsResponse) Reset()

func (*DatasetsResponse) String

func (x *DatasetsResponse) String() string

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient is the interface used by generated clients to send HTTP requests. It is fulfilled by *(net/http).Client, which is sufficient for most users. Users can provide their own implementation for special retry policies.

HTTPClient implementations should not follow redirects. Redirects are automatically disabled if *(net/http).Client is passed to client constructors. See the withoutRedirects function in this file for more details.

type PlanRequest

type PlanRequest struct {
	Spec string `protobuf:"bytes,1,opt,name=spec,proto3" json:"spec,omitempty"`
	// contains filtered or unexported fields
}

func (*PlanRequest) Descriptor deprecated

func (*PlanRequest) Descriptor() ([]byte, []int)

Deprecated: Use PlanRequest.ProtoReflect.Descriptor instead.

func (*PlanRequest) GetSpec

func (x *PlanRequest) GetSpec() string

func (*PlanRequest) ProtoMessage

func (*PlanRequest) ProtoMessage()

func (*PlanRequest) ProtoReflect

func (x *PlanRequest) ProtoReflect() protoreflect.Message

func (*PlanRequest) Reset

func (x *PlanRequest) Reset()

func (*PlanRequest) String

func (x *PlanRequest) String() string

type PlanResponse

type PlanResponse struct {
	PlanJson string `protobuf:"bytes,1,opt,name=plan_json,json=planJson,proto3" json:"plan_json,omitempty"`
	// contains filtered or unexported fields
}

func (*PlanResponse) Descriptor deprecated

func (*PlanResponse) Descriptor() ([]byte, []int)

Deprecated: Use PlanResponse.ProtoReflect.Descriptor instead.

func (*PlanResponse) GetPlanJson

func (x *PlanResponse) GetPlanJson() string

func (*PlanResponse) ProtoMessage

func (*PlanResponse) ProtoMessage()

func (*PlanResponse) ProtoReflect

func (x *PlanResponse) ProtoReflect() protoreflect.Message

func (*PlanResponse) Reset

func (x *PlanResponse) Reset()

func (*PlanResponse) String

func (x *PlanResponse) String() string

type PlotRequest

type PlotRequest struct {
	Spec   string `protobuf:"bytes,1,opt,name=spec,proto3" json:"spec,omitempty"`
	Format string `protobuf:"bytes,2,opt,name=format,proto3" json:"format,omitempty"`
	Theme  string `protobuf:"bytes,3,opt,name=theme,proto3" json:"theme,omitempty"`
	Width  int32  `protobuf:"varint,4,opt,name=width,proto3" json:"width,omitempty"`
	Height int32  `protobuf:"varint,5,opt,name=height,proto3" json:"height,omitempty"`
	// contains filtered or unexported fields
}

func (*PlotRequest) Descriptor deprecated

func (*PlotRequest) Descriptor() ([]byte, []int)

Deprecated: Use PlotRequest.ProtoReflect.Descriptor instead.

func (*PlotRequest) GetFormat

func (x *PlotRequest) GetFormat() string

func (*PlotRequest) GetHeight

func (x *PlotRequest) GetHeight() int32

func (*PlotRequest) GetSpec

func (x *PlotRequest) GetSpec() string

func (*PlotRequest) GetTheme

func (x *PlotRequest) GetTheme() string

func (*PlotRequest) GetWidth

func (x *PlotRequest) GetWidth() int32

func (*PlotRequest) ProtoMessage

func (*PlotRequest) ProtoMessage()

func (*PlotRequest) ProtoReflect

func (x *PlotRequest) ProtoReflect() protoreflect.Message

func (*PlotRequest) Reset

func (x *PlotRequest) Reset()

func (*PlotRequest) String

func (x *PlotRequest) String() string

type PlotResponse

type PlotResponse struct {
	Bytes    []byte   `protobuf:"bytes,1,opt,name=bytes,proto3" json:"bytes,omitempty"`
	Mime     string   `protobuf:"bytes,2,opt,name=mime,proto3" json:"mime,omitempty"`
	Warnings []string `protobuf:"bytes,3,rep,name=warnings,proto3" json:"warnings,omitempty"`
	// contains filtered or unexported fields
}

func (*PlotResponse) Descriptor deprecated

func (*PlotResponse) Descriptor() ([]byte, []int)

Deprecated: Use PlotResponse.ProtoReflect.Descriptor instead.

func (*PlotResponse) GetBytes

func (x *PlotResponse) GetBytes() []byte

func (*PlotResponse) GetMime

func (x *PlotResponse) GetMime() string

func (*PlotResponse) GetWarnings

func (x *PlotResponse) GetWarnings() []string

func (*PlotResponse) ProtoMessage

func (*PlotResponse) ProtoMessage()

func (*PlotResponse) ProtoReflect

func (x *PlotResponse) ProtoReflect() protoreflect.Message

func (*PlotResponse) Reset

func (x *PlotResponse) Reset()

func (*PlotResponse) String

func (x *PlotResponse) String() string

type Prism

type Prism interface {
	// Plot compiles a spec and renders it to bytes in the requested
	// format. SVG is always supported; PNG (P15) and PDF (P16) return
	// PRISM_RENDER_FORMAT_UNAVAILABLE in P14.
	Plot(context.Context, *PlotRequest) (*PlotResponse, error)

	// Validate returns ok=true with no errors when the spec is valid,
	// or ok=false with the structured error list when it isn't.
	Validate(context.Context, *ValidateRequest) (*ValidateResponse, error)

	// Scene runs stages 1-5 (resolve, plan, execute, encode) and
	// returns the Scene IR as JSON. The browser-side renderer
	// consumes this directly.
	Scene(context.Context, *SceneRequest) (*SceneResponse, error)

	// Plan returns the logical DAG that would execute the spec.
	// Useful for debugging and visualisation tooling.
	Plan(context.Context, *PlanRequest) (*PlanResponse, error)

	// ListDatasets returns the names + sources of every dataset in
	// the server's registry.
	ListDatasets(context.Context, *DatasetsRequest) (*DatasetsResponse, error)
}

Prism is the canonical RPC surface for the Prism visualization library. Every method except ListDatasets requires a spec; specs are JSON-encoded per the schemas under `schema/v1/`.

func NewPrismJSONClient

func NewPrismJSONClient(baseURL string, client HTTPClient, opts ...twirp.ClientOption) Prism

NewPrismJSONClient creates a JSON client that implements the Prism interface. It communicates using JSON and can be configured with a custom HTTPClient.

func NewPrismProtobufClient

func NewPrismProtobufClient(baseURL string, client HTTPClient, opts ...twirp.ClientOption) Prism

NewPrismProtobufClient creates a Protobuf client that implements the Prism interface. It communicates using Protobuf and can be configured with a custom HTTPClient.

type PrismServer

type PrismServer struct {
	// DatasetRegistry exposes the server-side aliases the Twirp
	// ListDatasets RPC enumerates. Optional; the zero value is an
	// EmptyDatasetRegistry.
	DatasetRegistry resolve.DatasetRegistry
	// Fs is the file system every spec read goes through. Optional;
	// the zero value is afero.NewOsFs().
	Fs afero.Fs
	// ExecOpts is merged into the executor options for Plot/Scene
	// requests. Use this to wire optional OTel hooks (D086) via
	// internal/observability.Hooks().
	ExecOpts plan.ExecOpts
}

PrismServer implements the generated prism.v1.Prism Twirp service. Field zero values produce a working server (in-memory backend, empty registry, OS file system).

func (*PrismServer) ListDatasets

func (s *PrismServer) ListDatasets(ctx context.Context, req *DatasetsRequest) (*DatasetsResponse, error)

ListDatasets implements the ListDatasets RPC. Registries that implement resolve.DatasetLister return their full alias list; registries that don't return an empty slice (no error).

func (*PrismServer) Plan

func (s *PrismServer) Plan(ctx context.Context, req *PlanRequest) (*PlanResponse, error)

Plan implements the Plan RPC. The DAG is rendered via the standard plan.RenderJSON emitter so the wire shape matches `prism plan --format json`.

func (*PrismServer) Plot

func (s *PrismServer) Plot(ctx context.Context, req *PlotRequest) (*PlotResponse, error)

Plot implements the Plot RPC. SVG and PDF render inline; PNG + canvas-json return PRISM_RENDER_FORMAT_UNAVAILABLE — the interceptor maps that code to twirp.Unimplemented per D085. PDF defaults to a single page (Paginate=false); multi-page output over the wire defers to a future proto-shape change.

func (*PrismServer) Scene

func (s *PrismServer) Scene(ctx context.Context, req *SceneRequest) (*SceneResponse, error)

Scene implements the Scene RPC. The Scene IR is returned as JSON text in SceneResponse.scene_json — agents (and the /prism/scene compatibility wrapper) parse it back into their own scene type.

func (*PrismServer) Validate

func (s *PrismServer) Validate(ctx context.Context, req *ValidateRequest) (*ValidateResponse, error)

Validate implements the Validate RPC. ok=true with no errors when the spec is valid; ok=false with the structured error list when not. Decode failures are surfaced as a single PRISM_SPEC_009 entry, matching the CLI behaviour.

type SceneRequest

type SceneRequest struct {
	Spec   string `protobuf:"bytes,1,opt,name=spec,proto3" json:"spec,omitempty"`
	Theme  string `protobuf:"bytes,2,opt,name=theme,proto3" json:"theme,omitempty"`
	Width  int32  `protobuf:"varint,3,opt,name=width,proto3" json:"width,omitempty"`
	Height int32  `protobuf:"varint,4,opt,name=height,proto3" json:"height,omitempty"`
	// contains filtered or unexported fields
}

func (*SceneRequest) Descriptor deprecated

func (*SceneRequest) Descriptor() ([]byte, []int)

Deprecated: Use SceneRequest.ProtoReflect.Descriptor instead.

func (*SceneRequest) GetHeight

func (x *SceneRequest) GetHeight() int32

func (*SceneRequest) GetSpec

func (x *SceneRequest) GetSpec() string

func (*SceneRequest) GetTheme

func (x *SceneRequest) GetTheme() string

func (*SceneRequest) GetWidth

func (x *SceneRequest) GetWidth() int32

func (*SceneRequest) ProtoMessage

func (*SceneRequest) ProtoMessage()

func (*SceneRequest) ProtoReflect

func (x *SceneRequest) ProtoReflect() protoreflect.Message

func (*SceneRequest) Reset

func (x *SceneRequest) Reset()

func (*SceneRequest) String

func (x *SceneRequest) String() string

type SceneResponse

type SceneResponse struct {
	SceneJson string `protobuf:"bytes,1,opt,name=scene_json,json=sceneJson,proto3" json:"scene_json,omitempty"`
	// contains filtered or unexported fields
}

func (*SceneResponse) Descriptor deprecated

func (*SceneResponse) Descriptor() ([]byte, []int)

Deprecated: Use SceneResponse.ProtoReflect.Descriptor instead.

func (*SceneResponse) GetSceneJson

func (x *SceneResponse) GetSceneJson() string

func (*SceneResponse) ProtoMessage

func (*SceneResponse) ProtoMessage()

func (*SceneResponse) ProtoReflect

func (x *SceneResponse) ProtoReflect() protoreflect.Message

func (*SceneResponse) Reset

func (x *SceneResponse) Reset()

func (*SceneResponse) String

func (x *SceneResponse) String() string

type TwirpServer

type TwirpServer interface {
	http.Handler

	// ServiceDescriptor returns gzipped bytes describing the .proto file that
	// this service was generated from. Once unzipped, the bytes can be
	// unmarshalled as a
	// google.golang.org/protobuf/types/descriptorpb.FileDescriptorProto.
	//
	// The returned integer is the index of this particular service within that
	// FileDescriptorProto's 'Service' slice of ServiceDescriptorProtos. This is a
	// low-level field, expected to be used for reflection.
	ServiceDescriptor() ([]byte, int)

	// ProtocGenTwirpVersion is the semantic version string of the version of
	// twirp used to generate this file.
	ProtocGenTwirpVersion() string

	// PathPrefix returns the HTTP URL path prefix for all methods handled by this
	// service. This can be used with an HTTP mux to route Twirp requests.
	// The path prefix is in the form: "/<prefix>/<package>.<Service>/"
	// that is, everything in a Twirp route except for the <Method> at the end.
	PathPrefix() string
}

TwirpServer is the interface generated server structs will support: they're HTTP handlers with additional methods for accessing metadata about the service. Those accessors are a low-level API for building reflection tools. Most people can think of TwirpServers as just http.Handlers.

func NewPrismServer

func NewPrismServer(svc Prism, opts ...interface{}) TwirpServer

NewPrismServer builds a TwirpServer that can be used as an http.Handler to handle HTTP requests that are routed to the right method in the provided svc implementation. The opts are twirp.ServerOption modifiers, for example twirp.WithServerHooks(hooks).

type ValidateError

type ValidateError struct {
	Code    string   `protobuf:"bytes,1,opt,name=code,proto3" json:"code,omitempty"`
	Message string   `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"`
	Fixups  []string `protobuf:"bytes,3,rep,name=fixups,proto3" json:"fixups,omitempty"`
	// contains filtered or unexported fields
}

func (*ValidateError) Descriptor deprecated

func (*ValidateError) Descriptor() ([]byte, []int)

Deprecated: Use ValidateError.ProtoReflect.Descriptor instead.

func (*ValidateError) GetCode

func (x *ValidateError) GetCode() string

func (*ValidateError) GetFixups

func (x *ValidateError) GetFixups() []string

func (*ValidateError) GetMessage

func (x *ValidateError) GetMessage() string

func (*ValidateError) ProtoMessage

func (*ValidateError) ProtoMessage()

func (*ValidateError) ProtoReflect

func (x *ValidateError) ProtoReflect() protoreflect.Message

func (*ValidateError) Reset

func (x *ValidateError) Reset()

func (*ValidateError) String

func (x *ValidateError) String() string

type ValidateRequest

type ValidateRequest struct {
	Spec string `protobuf:"bytes,1,opt,name=spec,proto3" json:"spec,omitempty"`
	// contains filtered or unexported fields
}

func (*ValidateRequest) Descriptor deprecated

func (*ValidateRequest) Descriptor() ([]byte, []int)

Deprecated: Use ValidateRequest.ProtoReflect.Descriptor instead.

func (*ValidateRequest) GetSpec

func (x *ValidateRequest) GetSpec() string

func (*ValidateRequest) ProtoMessage

func (*ValidateRequest) ProtoMessage()

func (*ValidateRequest) ProtoReflect

func (x *ValidateRequest) ProtoReflect() protoreflect.Message

func (*ValidateRequest) Reset

func (x *ValidateRequest) Reset()

func (*ValidateRequest) String

func (x *ValidateRequest) String() string

type ValidateResponse

type ValidateResponse struct {
	Ok     bool             `protobuf:"varint,1,opt,name=ok,proto3" json:"ok,omitempty"`
	Errors []*ValidateError `protobuf:"bytes,2,rep,name=errors,proto3" json:"errors,omitempty"`
	// contains filtered or unexported fields
}

func (*ValidateResponse) Descriptor deprecated

func (*ValidateResponse) Descriptor() ([]byte, []int)

Deprecated: Use ValidateResponse.ProtoReflect.Descriptor instead.

func (*ValidateResponse) GetErrors

func (x *ValidateResponse) GetErrors() []*ValidateError

func (*ValidateResponse) GetOk

func (x *ValidateResponse) GetOk() bool

func (*ValidateResponse) ProtoMessage

func (*ValidateResponse) ProtoMessage()

func (*ValidateResponse) ProtoReflect

func (x *ValidateResponse) ProtoReflect() protoreflect.Message

func (*ValidateResponse) Reset

func (x *ValidateResponse) Reset()

func (*ValidateResponse) String

func (x *ValidateResponse) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL