Documentation
¶
Overview ¶
Package client connects a host (the Panelarr server, or any program) to source plugins: managed binaries it starts itself, remote plugins it reaches by URL, and in-process plugins for tests. All three give the same Client.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrImageTooLarge = errors.New("client: image is larger than the limit")
ErrImageTooLarge is returned by ReadImage when an image is bigger than its limit.
Functions ¶
Types ¶
type Client ¶
type Client interface {
GetInfo(ctx context.Context) (*sourcev1.PluginInfo, error)
// GetConfig returns the plugin-level configuration, secrets left empty.
GetConfig(ctx context.Context) (*structpb.Struct, error)
// SetConfig replaces the plugin-level configuration and returns it as
// GetConfig does.
SetConfig(ctx context.Context, values *structpb.Struct) (*structpb.Struct, error)
Health(ctx context.Context) (*sourcev1.HealthResponse, error)
ListSources(ctx context.Context, req *sourcev1.ListSourcesRequest) (*sourcev1.ListSourcesResponse, error)
GetSource(ctx context.Context, req *sourcev1.GetSourceRequest) (*sourcev1.GetSourceResponse, error)
GetFilters(ctx context.Context, req *sourcev1.GetFiltersRequest) (*sourcev1.GetFiltersResponse, error)
Popular(ctx context.Context, req *sourcev1.PopularRequest) (*sourcev1.PopularResponse, error)
Latest(ctx context.Context, req *sourcev1.LatestRequest) (*sourcev1.LatestResponse, error)
Search(ctx context.Context, req *sourcev1.SearchRequest) (*sourcev1.SearchResponse, error)
ResolveUrl(ctx context.Context, req *sourcev1.ResolveUrlRequest) (*sourcev1.ResolveUrlResponse, error)
GetSeries(ctx context.Context, req *sourcev1.GetSeriesRequest) (*sourcev1.GetSeriesResponse, error)
ListChapters(ctx context.Context, req *sourcev1.ListChaptersRequest) (*sourcev1.ListChaptersResponse, error)
ListPages(ctx context.Context, req *sourcev1.ListPagesRequest) (*sourcev1.ListPagesResponse, error)
GetSettingsSchema(ctx context.Context, req *sourcev1.GetSettingsSchemaRequest) (*sourcev1.GetSettingsSchemaResponse, error)
GetSettings(ctx context.Context, req *sourcev1.GetSettingsRequest) (*sourcev1.GetSettingsResponse, error)
SetSettings(ctx context.Context, req *sourcev1.SetSettingsRequest) (*sourcev1.SetSettingsResponse, error)
// The package calls (plugins with the PACKAGES capability). InstallPackage
// and UpdatePackage can take minutes: give them a long deadline.
ListPackages(ctx context.Context, req *sourcev1.ListPackagesRequest) (*sourcev1.ListPackagesResponse, error)
GetPackage(ctx context.Context, req *sourcev1.GetPackageRequest) (*sourcev1.GetPackageResponse, error)
InstallPackage(ctx context.Context, req *sourcev1.InstallPackageRequest) (*sourcev1.InstallPackageResponse, error)
UpdatePackage(ctx context.Context, req *sourcev1.UpdatePackageRequest) (*sourcev1.UpdatePackageResponse, error)
UninstallPackage(ctx context.Context, req *sourcev1.UninstallPackageRequest) (*sourcev1.UninstallPackageResponse, error)
SetPackageSettings(ctx context.Context, req *sourcev1.SetPackageSettingsRequest) (*sourcev1.SetPackageSettingsResponse, error)
ListOrigins(ctx context.Context, req *sourcev1.ListOriginsRequest) (*sourcev1.ListOriginsResponse, error)
RefreshOrigin(ctx context.Context, req *sourcev1.RefreshOriginRequest) (*sourcev1.RefreshOriginResponse, error)
ReloadPackage(ctx context.Context, req *sourcev1.ReloadPackageRequest) (*sourcev1.ReloadPackageResponse, error)
// SetSourceHealthCheck (plugins with the HEALTH_CHECKS capability).
SetSourceHealthCheck(ctx context.Context, req *sourcev1.SetSourceHealthCheckRequest) (*sourcev1.SetSourceHealthCheckResponse, error)
// The job calls (plugins with the JOBS capability). RunJob returns once the
// run has started; follow it with GetJobRun.
ListJobs(ctx context.Context, req *sourcev1.ListJobsRequest) (*sourcev1.ListJobsResponse, error)
GetJob(ctx context.Context, req *sourcev1.GetJobRequest) (*sourcev1.GetJobResponse, error)
ListJobRuns(ctx context.Context, req *sourcev1.ListJobRunsRequest) (*sourcev1.ListJobRunsResponse, error)
GetJobRun(ctx context.Context, req *sourcev1.GetJobRunRequest) (*sourcev1.GetJobRunResponse, error)
RunJob(ctx context.Context, req *sourcev1.RunJobRequest) (*sourcev1.RunJobResponse, error)
CancelJobRun(ctx context.Context, req *sourcev1.CancelJobRunRequest) (*sourcev1.CancelJobRunResponse, error)
// FetchImage starts streaming an image. Read it with Recv, or use
// [ReadImage].
FetchImage(ctx context.Context, req *sourcev1.FetchImageRequest) (ImageStream, error)
// GetNetworkProfile returns the profile a source uses and its origin.
GetNetworkProfile(ctx context.Context, sourceID string) (*sourcev1.GetNetworkProfileResponse, error)
// SetNetworkProfile hands the plugin a source's network profile; nil
// removes the pushed profile.
SetNetworkProfile(ctx context.Context, sourceID string, profile *sourcev1.NetworkProfile) error
// Close ends the connection and, for managed plugins, the process.
Close() error
}
Client talks to one source plugin. Errors from the plugin come back as *plugin.Error (with the code, the error reason and any retry hint) where the plugin gave a status.
func GRPC ¶
func GRPC(conn grpc.ClientConnInterface) Client
GRPC returns a client over an existing gRPC connection, e.g. one a host dialled itself.
func InProcess ¶
InProcess returns a client that calls p directly, without a process or a network in between. Messages are cloned on the way, as a real transport would copy them. Meant for tests.
func Managed ¶
func Managed(path string, opts ManagedOptions) (Client, error)
Managed starts the plugin binary at path as a child process (go-plugin handshake, gRPC on a local socket) and returns a client for it. Close stops the process.
func Remote ¶
func Remote(baseURL string, opts RemoteOptions) Client
Remote returns a client for a plugin running as a service at baseURL, e.g. "http://source-plugin:8904". It speaks gRPC unless opts.Connect is set, so it works with any gRPC plugin, in any language.
type ImageStream ¶
type ImageStream interface {
// Recv returns the next message, or io.EOF after the last one.
Recv() (*sourcev1.FetchImageResponse, error)
// Close stops reading and releases the stream.
Close() error
}
ImageStream reads the messages of FetchImage: the metadata first, then the bytes.
type ManagedOptions ¶
type ManagedOptions struct {
// Args are passed to the plugin binary.
Args []string
// Env is added to the plugin's environment.
Env []string
// Logger receives the plugin's log output. Defaults to no output.
Logger hclog.Logger
}
ManagedOptions configure Managed.
type RemoteOptions ¶
type RemoteOptions struct {
// APIKey is sent as "Authorization: Bearer <key>".
APIKey string
// HTTPClient overrides the HTTP client. The default speaks HTTP/2,
// cleartext for http:// URLs and TLS for https://, as gRPC needs.
HTTPClient *http.Client
// Connect uses the Connect protocol instead of gRPC. gRPC is the
// protocol every plugin must speak; Connect is an optional extra that
// also works over HTTP/1.1.
Connect bool
}
RemoteOptions configure Remote.