Documentation
¶
Overview ¶
Package sdk provides a client for the EasyP API Service.
The SDK simplifies interaction with the EasyP API Service, allowing you to list available plugins and execute code generation requests remotely.
Example usage:
c, err := sdk.NewClient("localhost:23410", sdk.WithInsecure())
if err != nil {
log.Fatal(err)
}
defer c.Close()
plugins, err := c.ListPlugins(context.Background())
Filtering is an option, so a call can gain one without changing shape:
plugins, err := c.ListPlugins(ctx, sdk.WithFilter(sdk.PluginFilter{Group: "grpc"}))
if err != nil {
log.Fatal(err)
}
Index ¶
- Constants
- type Client
- func (c *Client) Close() error
- func (c *Client) CreatePlugin(ctx context.Context, group, name, version string, pluginConfig map[string]any, ...) (*generator.PluginInfo, error)
- func (c *Client) DeletePlugin(ctx context.Context, group, name, version string) error
- func (c *Client) GenerateCode(ctx context.Context, pluginName string, req *pluginpb.CodeGeneratorRequest) (*pluginpb.CodeGeneratorResponse, error)
- func (c *Client) ListPlugins(ctx context.Context, opts ...ListOption) ([]*generator.PluginInfo, error)
- func (c *Client) UpdatePlugin(ctx context.Context, group, name, version string, pluginConfig map[string]any, ...) (*generator.PluginInfo, error)
- type ListOption
- type MetricsCollector
- type Option
- func WithCreatePluginTimeout(d time.Duration) Option
- func WithGenerateCodeTimeout(d time.Duration) Option
- func WithHealthCheck(interval time.Duration) Option
- func WithInsecure() Option
- func WithKeepaliveParams(params keepalive.ClientParameters) Option
- func WithListPluginsTimeout(d time.Duration) Option
- func WithLoggingInterceptor(logger *slog.Logger) Option
- func WithMaxRecvMsgSize(size int) Option
- func WithMaxRetries(n int) Option
- func WithMetricsInterceptor(collector MetricsCollector) Option
- func WithRetryBaseDelay(d time.Duration) Option
- func WithRetryMaxDelay(d time.Duration) Option
- func WithToken(token string) Option
- func WithTransportCredentials(creds credentials.TransportCredentials) Option
- func WithUnaryInterceptor(i grpc.UnaryClientInterceptor) Option
- type PluginFilter
Constants ¶
const DefaultMaxRecvMsgSize = 64 << 20
DefaultMaxRecvMsgSize is the largest response the client accepts, matching the service's own default output cap.
gRPC's default is 4 MiB, which is smaller than the output a plugin is permitted to produce. Left alone, a large generation runs to completion on the server and then fails at the client with ResourceExhausted — all the work done, none of it delivered.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a client for the EasyP API Service.
func (*Client) Close ¶
Close closes the underlying gRPC connection. If a health monitor is running, it is stopped first.
func (*Client) CreatePlugin ¶
func (c *Client) CreatePlugin( ctx context.Context, group, name, version string, pluginConfig map[string]any, tags []string, ) (*generator.PluginInfo, error)
CreatePlugin registers a new plugin in the service. When S3 binary storage is enabled on the service, the plugin archive must be pushed to storage beforehand (easyp-svc plugins push): the service verifies its presence and records its sha256 checksum at registration.
func (*Client) DeletePlugin ¶
DeletePlugin removes a plugin registration. The archive in object storage is left alone.
func (*Client) GenerateCode ¶
func (c *Client) GenerateCode( ctx context.Context, pluginName string, req *pluginpb.CodeGeneratorRequest, ) (*pluginpb.CodeGeneratorResponse, error)
GenerateCode executes a plugin to generate code.
func (*Client) ListPlugins ¶
func (c *Client) ListPlugins(ctx context.Context, opts ...ListOption) ([]*generator.PluginInfo, error)
ListPlugins retrieves the complete list of available plugins, optionally filtered. The server pages its listing; this walks every page before returning, so the caller sees one list, not the first hundred entries. The configured list timeout spans the whole walk.
Options rather than a variadic filter: `filter ...PluginFilter` was an optional argument wearing a variadic's clothes, and a second option could only have been added by changing the signature — which, past v1, means a new method with a worse name.
func (*Client) UpdatePlugin ¶
func (c *Client) UpdatePlugin( ctx context.Context, group, name, version string, pluginConfig map[string]any, tags []string, paths ...string, ) (*generator.PluginInfo, error)
UpdatePlugin replaces the config and tags of a registered plugin.
paths selects what to replace: "config", "tags", or both. Passing none replaces both, which is what the service does with an empty mask. Updating tags alone leaves the plugin's command line untouched — which is the point of the mask, since resending a command line to change a label is how a registry entry ends up pointing at the wrong binary.
type ListOption ¶
type ListOption interface {
// contains filtered or unexported methods
}
ListOption configures a ListPlugins call.
func WithFilter ¶
func WithFilter(filter PluginFilter) ListOption
WithFilter narrows the listing to plugins matching every non-empty field.
type MetricsCollector ¶
type MetricsCollector interface {
RecordCall(method string, duration time.Duration, code codes.Code)
}
MetricsCollector is the interface for collecting SDK call metrics.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option configures the client.
func WithCreatePluginTimeout ¶
WithCreatePluginTimeout sets the default timeout for CreatePlugin, UpdatePlugin and DeletePlugin. The default is generous because with object storage enabled the service streams the whole plugin archive to checksum it.
func WithGenerateCodeTimeout ¶
WithGenerateCodeTimeout sets the default timeout for GenerateCode calls.
func WithHealthCheck ¶
WithHealthCheck enables periodic connection health monitoring with the given interval.
func WithInsecure ¶
func WithInsecure() Option
WithInsecure disables Transport Security (TLS). Use this option for local development or testing.
func WithKeepaliveParams ¶
func WithKeepaliveParams(params keepalive.ClientParameters) Option
WithKeepaliveParams sets gRPC keepalive parameters for the connection.
func WithListPluginsTimeout ¶
WithListPluginsTimeout sets the default timeout for ListPlugins calls.
func WithLoggingInterceptor ¶
WithLoggingInterceptor adds a built-in logging interceptor that records the RPC method, call duration, and response status code.
func WithMaxRecvMsgSize ¶
WithMaxRecvMsgSize sets the largest response the client will accept, in bytes. Raise it when the service is configured to allow plugin output larger than DefaultMaxRecvMsgSize; a value of zero or less restores the default.
func WithMaxRetries ¶
WithMaxRetries sets the maximum number of retry attempts for transient errors.
func WithMetricsInterceptor ¶
func WithMetricsInterceptor(collector MetricsCollector) Option
WithMetricsInterceptor adds a built-in metrics interceptor that records call counts, durations, and response codes via the provided MetricsCollector.
func WithRetryBaseDelay ¶
WithRetryBaseDelay sets the base delay between retry attempts.
func WithRetryMaxDelay ¶
WithRetryMaxDelay caps the backoff between retries. The delay grows exponentially from WithRetryBaseDelay and stops here.
func WithToken ¶
WithToken authenticates the client with a write token.
Reads are anonymous, so this is only needed for CreatePlugin, UpdatePlugin and DeletePlugin. The token travels in the authorization header, which means it is only as protected as the connection: pair it with TLS.
func WithTransportCredentials ¶
func WithTransportCredentials(creds credentials.TransportCredentials) Option
WithTransportCredentials sets custom transport credentials.
func WithUnaryInterceptor ¶
func WithUnaryInterceptor(i grpc.UnaryClientInterceptor) Option
WithUnaryInterceptor appends a gRPC unary client interceptor to the chain.
type PluginFilter ¶
type PluginFilter struct {
// Group matches exactly, e.g. "protocolbuffers".
Group string
// Name matches exactly within the group, e.g. "go".
Name string
// Version matches exactly, e.g. "v1.36.10".
Version string
// Tags must all be present on a plugin for it to match.
Tags []string
}
PluginFilter narrows a plugin listing. Empty fields are ignored.
The service applies these itself, so a filter is a smaller response rather than a smaller slice: the client does not re-check the result. It used to, and a second pass could only ever differ from the server's own filtering by hiding a disagreement between the two.
Source Files