Skip to content

Go client library (vsctl)

import "vivesound.com/sdk/go/vsctl"

Package vsctl is a Go client library for ViveEngine.

ViveEngine is an audio orchestration engine for desktop. It sits between audio applications and the operating system, and lets you inject real-time effects into audio streams, capture audio, reroute streams between applications and devices, and add live captions.

The package wraps the generated gRPC client and exposes the engine Control API as an idiomatic Go interface.

Start here:

Index

Constants

const (
    // NoTimeout disables the timeout when used as a ConnectTimeout,
    // RequestTimeout, or CloseTimeout. The operation then waits indefinitely.
    NoTimeout time.Duration = -1

    // DefaultConnectTimeout is the ConnectTimeout used when it is left zero.
    // It is NoTimeout, so connecting waits indefinitely by default.
    DefaultConnectTimeout = NoTimeout

    // DefaultRequestTimeout is the RequestTimeout used when it is left zero.
    DefaultRequestTimeout = 1 * time.Minute

    // DefaultCloseTimeout is the CloseTimeout used when it is left zero.
    DefaultCloseTimeout = 10 * time.Second
)

Variables

var (
    // ErrClientConfigInvalid indicates invalid EngineConfig.
    // For example missing required field.
    //
    // Implements:
    //  - Error
    //  - ConfigurationError
    //
    // Corresponding gRPC statuses:
    //  - none (client-side condition)
    ErrClientConfigInvalid = newConfigurationErr("invalid client config")

    // ErrEngineNotDiscovered indicates that the client didn't find the engine to connect.
    // Can happen when trying to use the client when the engine is not properly installed.
    //
    // Implements:
    //  - Error
    //  - ConnectionError
    //
    // Corresponding gRPC statuses:
    //  - none (client-side condition)
    ErrEngineNotDiscovered = newConnectionErr("no engine discovered")

    // ErrEngineUnavailable indicates that the client either can't establish connection to
    // the engine, or lost existing connection, or client session expired on server and is
    // not usable. Can happen if active user switches and engine drops all existing session.
    // Also can happen if the engine isn't running or restarts.
    //
    // Implements:
    //  - Error
    //  - ConnectionError
    //
    // Corresponding gRPC statuses:
    //  - UNAVAILABLE
    ErrEngineUnavailable = newConnectionErr("no connection to engine")

    // ErrEngineVersionMismatch indicates attempt to use engine with incompatible version.
    // Can happen when trying to use older engine with newer client.
    //
    // Implements:
    //  - Error
    //  - CompatibilityError
    //
    // Corresponding gRPC statuses:
    //  - UNIMPLEMENTED
    ErrEngineVersionMismatch = newCompatibilityErr("incompatible engine version")

    // ErrEngineUnexpectedResponse indicates that the engine returned a successful
    // response that is semantically invalid or incomplete, implying a client/engine
    // protocol or version mismatch. For example, OpenSession returned an empty
    // session token or a missing/non-positive renewal interval.
    //
    // Implements:
    //  - Error
    //  - CompatibilityError
    //
    // Corresponding gRPC statuses:
    //  - none (client-side validation of a successful response)
    ErrEngineUnexpectedResponse = newCompatibilityErr("unexpected engine response")

    // ErrEngineFault indicates temporary engine failure.
    // The client is recommended to re-create session and retry.
    // Also used as fallback for unmapped engine statuses.
    //
    // Implements:
    //  - Error
    //  - RuntimeError
    //
    // Corresponding gRPC statuses:
    //  - ABORTED
    //  - INTERNAL
    //  - any other engine status not otherwise mapped
    ErrEngineFault = newRuntimeErr("engine fault")

    // ErrRequestInvalid indicates that request is ill-formed and rejected by engine.
    // For example, a required field is empty, or mutually exclusive fields are set.
    //
    // Implements:
    //  - Error
    //  - RequestError
    //
    // Corresponding gRPC statuses:
    //  - INVALID_ARGUMENT
    ErrRequestInvalid = newRequestErr("invalid request")

    // ErrResourceNotFound indicates that requested identifier was not found.
    // For example, client requested to read unknown device ID.
    //
    // Implements:
    //  - Error
    //  - RequestError
    //
    // Corresponding gRPC statuses:
    //  - NOT_FOUND
    ErrResourceNotFound = newRequestErr("resource not found")

    // ErrResourceAlreadyExists indicates that requested identifier already exists.
    // For example, client requested to create duplicate effect ID.
    //
    // Implements:
    //  - Error
    //  - RequestError
    //
    // Corresponding gRPC statuses:
    //  - ALREADY_EXISTS
    ErrResourceAlreadyExists = newRequestErr("resource already exists")

    // ErrResourceExhausted indicates that the engine rejected operation because some
    // limit was reached. For example, available number of license activations, or maximum
    // number of sessions.
    //
    // Implements:
    //  - Error
    //  - RequestError
    //
    // Corresponding gRPC statuses:
    //  - RESOURCE_EXHAUSTED
    ErrResourceExhausted = newRequestErr("resource exhausted")

    // ErrPermissionDenied indicates that engine rejected operation because the client is
    // not permitted to do it. For example, client tries to enable processing without
    // active license, or processing is currently locked by another edition of the engine.
    //
    // Implements:
    //  - Error
    //  - RequestError
    //
    // Corresponding gRPC statuses:
    //  - PERMISSION_DENIED
    ErrPermissionDenied = newRequestErr("permission denied")

    // ErrClientClosed indicates that operation was interrupted locally by Close().
    // Close() aborts all ongoing requests and make them return ErrClientClosed.
    // Close() itself does not return this error.
    //
    // Implements:
    //  - Error
    //  - LifecycleError
    //
    // Corresponding gRPC statuses:
    //  - none (client-side condition)
    ErrClientClosed = newLifecycleErr("client is closed")

    // ErrRequestTimeout indicates that request was aborted by timeout from EngineConfig.
    // It can be ConnectTimeout, RequestTimeout, or CloseTimeout depending on the operation.
    //
    // Implements:
    //  - Error
    //  - LifecycleError
    //
    // Corresponding gRPC statuses:
    //  - DEADLINE_EXCEEDED (client-side condition)
    ErrRequestTimeout = newLifecycleErr("request timed out")

    // ErrRequestCanceled indicates that request was aborted by canceling per-request
    // context provided by user. In this case error will also contain value returned
    // by context.Cause() or context.Canceled.
    //
    // Implements:
    //  - Error
    //  - LifecycleError
    //
    // Corresponding gRPC statuses:
    //  - CANCELLED (client-side condition)
    ErrRequestCanceled = newLifecycleErr("request canceled")
)

DiscoveryDir is the directory searched for engine metadata files. Defaults to the platform-specific system location.

var DiscoveryDir = defaultDiscoveryDir()

type CompatibilityError

CompatibilityError indicates that the client and engine versions are not compatible with each other.

Values:

Example:

var compErr vsctl.CompatibilityError
if errors.As(err, &compErr) { ... }

type CompatibilityError interface {
    Error
    // contains filtered or unexported methods
}

type ConfigurationError

ConfigurationError indicates invalid or incomplete client configuration detected locally before any request is sent to the engine.

Values:

Example:

var cfgErr vsctl.ConfigurationError
if errors.As(err, &cfgErr) { ... }

type ConfigurationError interface {
    Error
    // contains filtered or unexported methods
}

type ConnectMode

ConnectMode selects how connecting behaves when the requested UserName is not the currently active OS user.

type ConnectMode int

const (
    // ConnectWaitUser blocks connecting until the requested user becomes the
    // active user. This is the default.
    ConnectWaitUser ConnectMode = iota
    // ConnectFailFast makes connecting fail immediately when the requested user
    // is not the active user.
    ConnectFailFast
)

type ConnectionError

ConnectionError indicates that the engine cannot be reached: no engine was discovered, the connection could not be established, or an established connection or session was lost.

Values:

Example:

var connErr vsctl.ConnectionError
if errors.As(err, &connErr) { ... }

type ConnectionError interface {
    Error
    // contains filtered or unexported methods
}

type EngineClient

EngineClient is a client for ViveEngine Control API.

It wraps a gRPC connection and an engine session, and exposes each engine RPC as a Go method. On top of gRPC, it adds:

  • Session management (opens a session on connect, closes it on disconnect, and performs periodic renewal in background to keep the session alive).

  • Idiomatic API (RPC methods, DTO structs, contexts, timeouts, channels).

  • Modern error handling (with error chains and error categories via errors.As).

Usage

Construct and connect the client in one call:

cl, err := vsctl.ConnectEngine(context.Background(), vsctl.EngineConfig{})

Do the same, but manually step by step:

// Discover the RPC address of installed ViveEngine
meta, err := vsctl.DefaultEngine()

// Create a gRPC connection
conn, err := grpc.NewClient(
    meta.RpcAddress, grpc.WithTransportCredentials(insecure.NewCredentials()))

// Create a client (not connected yet)
cl, err := vsctl.NewEngineClient(context.Background(), vsctl.EngineConfig{})

// Connect client to the engine
err = cl.Connect(context.Background())

Call an RPC method:

mode, err := cl.GetRunMode(context.Background())

fmt.Println(mode.InputProcessing.Enabled)
fmt.Println(mode.OutputProcessing.Enabled)

Close the connection:

err := cl.Close()

Auto-connect

If you call RPC method on a not-yet-connected client (constructed by NewEngineClient), the very first RPC call will automatically connect.

This behavior matches underlying gRPC connection, which auto-connects as well, but at the transport level.

Thread-safety

EngineClient is fully thread-safe. Concurrent EngineClient.Connect and EngineClient.Close calls are internally serialized, but RPC method calls normally don't block each other.

EngineClient.Close call interrupt any other pending calls, including EngineClient.Connect.

Cancellation

Each RPC call has three client-side cancellation paths:

Errors

EngineClient returns chained errors. Usually chain includes single Error which you can detect via errors.As. It is possible to distinguish more granular error categories and error codes; see Error.

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

func ConnectEngine 

func ConnectEngine(connectCtx context.Context, config EngineConfig) (
    cl *EngineClient, err error,
)

ConnectEngine creates an EngineClient and connects it in one step.

It performs the following steps:

  • validate and default config;
  • if config.Address is empty, discover the default installed engine via DefaultEngine;
  • construct the gRPC connection;
  • construct the client via NewEngineClient;
  • connect the client via EngineClient.Connect (establish gRPC connection, open the engine session, and start the background keepalive).

The caller owns the returned client and must call EngineClient.Close to release its resources.

func NewEngineClient 

func NewEngineClient(rpcConn *grpc.ClientConn, config EngineConfig) (
    *EngineClient, error,
)

NewEngineClient wraps an existing gRPC connection into an EngineClient without connecting.

No network requests are made: the connection is not established and no session is opened until EngineClient.Connect is called or the first RPC auto-connects.

The client takes ownership of rpcConn, so EngineClient.Close closes it.

The caller owns the returned client and must call EngineClient.Close to release its resources.

func (*EngineClient) Connect 

func (cl *EngineClient) Connect(ctx context.Context) (err error)

Connect opens the engine session and starts the background keepalive.

It performs the following steps:

  • open the engine session, establishing the gRPC connection if it is not established yet;
  • start the background keepalive.

It is safe to call concurrently and is idempotent: once a connect succeeds, further calls return nil immediately. Calling it explicitly is optional, since RPC methods auto-connect on first use.

A concurrent EngineClient.Close aborts an in-progress connect.

func (*EngineClient) Close 

func (cl *EngineClient) Close() (err error)

Close shuts down the client and releases all resources.

It performs the following steps:

  • cancel pending and future calls, which then fail with ErrClientClosed;
  • wait for in-flight calls to finish;
  • stop the keepalive;
  • close the engine session;
  • close the underlying gRPC connection.

Close is idempotent: subsequent calls return the same error.

func (*EngineClient) Context 

func (cl *EngineClient) Context() context.Context

Context returns the client's internal context. It can be used to monitor when the client is closed: the context is cancelled on Close.

func (*EngineClient) Conn 

func (cl *EngineClient) Conn() *grpc.ClientConn

Conn returns the underlying gRPC connection. It is owned by the client; do not close it directly, use Close instead.

func (*EngineClient) GetLicense 

func (cl *EngineClient) GetLicense(ctx context.Context) (
    result *vsapi.LicenseState, err error,
)

GetLicense queries the current license state.

Returns the current LicenseState without changing it. The state reports the activation type and, when a license is active, either full or trial activation details.

func (*EngineClient) ActivateTrial 

func (cl *EngineClient) ActivateTrial(ctx context.Context) (
    result *vsapi.LicenseState, err error,
)

ActivateTrial activates a time-limited trial license and returns the resulting LicenseState. A trial requires no credentials and expires after a fixed period.

The call contacts the licensing service and may take noticeably longer than other requests. It fails if the edition does not permit a trial or if the service rejects the activation.

func (*EngineClient) ActivateWithKey 

func (cl *EngineClient) ActivateWithKey(ctx context.Context, key string) (
    result *vsapi.LicenseState, err error,
)

ActivateWithKey activates a full license using the given license key and returns the resulting LicenseState. The activation is granted to this computer and counts against the license's available activations.

The call contacts the licensing service and may take noticeably longer than other requests. It fails if the edition does not permit key activation or if the service rejects the activation.

func (*EngineClient) ActivateWithCreds 

func (cl *EngineClient) ActivateWithCreds(
    ctx context.Context, email, password string,
) (
    result *vsapi.LicenseState, err error,
)

ActivateWithCreds activates a full license using user account credentials (email and password) and returns the resulting LicenseState. The activation is granted to this computer and counts against the license's available activations.

The call contacts the licensing service and may take noticeably longer than other requests. It fails if the edition does not permit credentials activation or if the service rejects the activation.

func (*EngineClient) DeactivateLicense 

func (cl *EngineClient) DeactivateLicense(ctx context.Context) (
    result *vsapi.LicenseState, err error,
)

DeactivateLicense releases the current activation and returns the updated LicenseState. This frees the activation so it can be used on another computer. Once deactivated, the engine stops audio processing until a license is activated again.

func (*EngineClient) ListPlugins 

func (cl *EngineClient) ListPlugins(ctx context.Context) (
    result []vsapi.Plugin, err error,
)

ListPlugins lists loaded plugins.

Returns one Plugin per plugin currently loaded in the engine. This lists loaded plugin binaries, not the instances created from them for use as effects.

func (*EngineClient) LoadPlugin 

func (cl *EngineClient) LoadPlugin(
    ctx context.Context, pluginType vsapi.PluginType, location string,
) (
    result *vsapi.Plugin, err error,
)

LoadPlugin loads the plugin binary at location, treating it as the given pluginType, and returns the resulting Plugin with its assigned UID. The UID can then be used to create instances of the plugin as PluginEffect effects and to address the plugin in messaging calls.

Loading is persistent: the plugin is remembered and loaded again automatically after a restart. The call is idempotent; loading a plugin that is already loaded returns its existing UID without loading it twice. The UID is stable across unload and reload of the same plugin.

func (*EngineClient) UnloadPlugin 

func (cl *EngineClient) UnloadPlugin(ctx context.Context, pluginUID string) (
    err error,
)

UnloadPlugin unloads the plugin identified by pluginUID and removes it from the persistent set, so it is no longer loaded after a restart. All instances created from the plugin are destroyed and their effects are removed from the flows that contained them.

func (*EngineClient) SendMessage 

func (cl *EngineClient) SendMessage(
    ctx context.Context,
    targetEffect vsapi.EffectSelector,
    messagePayload *anypb.Any,
) (
    err error,
)

SendMessage delivers messagePayload to the single plugin instance selected by targetEffect. The payload is an opaque protobuf message understood by the plugin. The message is delivered asynchronously; the call returns once the message is accepted, not once the plugin has processed it.

func (*EngineClient) BroadcastMessage 

func (cl *EngineClient) BroadcastMessage(
    ctx context.Context, targetPluginUID string, messagePayload *anypb.Any,
) (
    err error,
)

BroadcastMessage delivers messagePayload to every instance created from the plugin identified by targetPluginUID. Aside from selecting all instances of a plugin rather than one instance, it behaves like SendMessage.

func (*EngineClient) ReceiveMessages 

func (cl *EngineClient) ReceiveMessages(
    ctx context.Context,
    sourcePluginUID string,
    sourceEffects []vsapi.EffectSelector,
) (
    <-chan vsapi.PluginMessage,
    <-chan error,
)

ReceiveMessages subscribes to messages produced by the plugin selected by sourcePluginUID, optionally narrowed to the instances listed in sourceEffects, and opens a stream of them. If sourceEffects is empty, messages from all instances of the plugin are received.

Messages are delivered on the returned channel until the stream ends, the session ends, or ctx is cancelled. Any error is reported on the returned error channel. Once the subscription is established, every matching message is guaranteed to be delivered, including messages from effects created afterwards.

This call aggregates the underlying subscribe, receive, and unsubscribe requests. By the time it returns, the subscription is either established or has failed. On success the returned channels are open and every message produced after the return is guaranteed to be delivered; on failure the error channel already holds the error and both channels are already closed.

If the stream later fails, the error is sent on the error channel and both channels are closed, so the caller must select on both channels. Cancelling ctx unsubscribes and closes both channels, reporting the cancellation as ErrRequestCanceled on the error channel.

func (*EngineClient) GetRunMode 

func (cl *EngineClient) GetRunMode(ctx context.Context) (
    result *vsapi.RunMode, err error,
)

GetRunMode retrieves the current run mode.

Returns a RunMode indicating whether input and output processing are currently enabled or disabled.

func (*EngineClient) SetRunMode 

func (cl *EngineClient) SetRunMode(
    ctx context.Context,
    input *vsapi.ProcessingMode,
    output *vsapi.ProcessingMode,
) (
    result *vsapi.RunMode,
    err error,
)

SetRunMode enables or disables the engine for input, output, or both. Only the directions given as non-nil are updated; a nil input or output retains its current value. Returns the resulting RunMode after the change is applied.

func (*EngineClient) QueryFlow 

func (cl *EngineClient) QueryFlow(
    ctx context.Context, selector vsapi.FlowSelector,
) (
    result *vsapi.FlowConfig, err error,
)

QueryFlow retrieves the configuration of a flow.

Locates the flow by selector and returns its FlowConfig, with the current route and effect chain.

func (*EngineClient) ConfigureFlow 

func (cl *EngineClient) ConfigureFlow(
    ctx context.Context, selector vsapi.FlowSelector, config vsapi.FlowConfig,
) (
    result *vsapi.FlowConfig, err error,
)

ConfigureFlow locates the flow by selector and replaces its configuration with config, setting its route and effect chain in one call. Returns the resulting FlowConfig.

If the route is omitted, the default route is used. An empty effect chain means default processing, that is, no processing.

func (*EngineClient) QueryEffect 

func (cl *EngineClient) QueryEffect(
    ctx context.Context, selector vsapi.FlowSelector, effectKey uint32,
) (
    result *vsapi.EffectConfig, err error,
)

QueryEffect retrieves a single effect from a flow.

Locates the effect by selector and effectKey, and returns its EffectConfig. Fails if no such effect exists.

func (*EngineClient) InsertEffect 

func (cl *EngineClient) InsertEffect(
    ctx context.Context,
    selector vsapi.FlowSelector,
    effectConfig vsapi.EffectConfig,
    chainPosition uint32,
) (
    result *vsapi.EffectConfig,
    err error,
)

InsertEffect locates the flow by selector and inserts effectConfig into its effect chain at the zero-based chainPosition, shifting later effects toward the end. Returns the resulting EffectConfig. Fails if chainPosition is past the end of the chain, or if the effect key is already in use within that chain.

func (*EngineClient) ConfigureEffect 

func (cl *EngineClient) ConfigureEffect(
    ctx context.Context,
    selector vsapi.FlowSelector,
    effectConfig vsapi.EffectConfig,
) (
    result *vsapi.EffectConfig,
    err error,
)

ConfigureEffect reconfigures a single effect in a flow.

Locates the effect by selector and the effect key of effectConfig, and replaces it, keeping its position. Returns the resulting EffectConfig. Fails if no such effect exists.

func (*EngineClient) DeleteEffect 

func (cl *EngineClient) DeleteEffect(
    ctx context.Context, selector vsapi.FlowSelector, effectKey uint32,
) (
    err error,
)

DeleteEffect removes a single effect from a flow.

Locates the effect by selector and effectKey, and removes it, shifting later effects toward the start. Fails if no such effect exists.

func (*EngineClient) ConfigureCaptions 

func (cl *EngineClient) ConfigureCaptions(
    ctx context.Context, config vsapi.CaptionsConfig,
) (
    result *vsapi.CaptionsConfig, err error,
)

ConfigureCaptions selects the captioning provider and configures its credentials.

Sets the provider in config and returns the resulting CaptionsConfig. The built-in provider needs no credentials. To use your own cloud account, select the Bring Your Own Cloud provider and supply the keys in the config.

func (*EngineClient) ReceiveCaptions 

func (cl *EngineClient) ReceiveCaptions(ctx context.Context) (
    <-chan vsapi.Caption, <-chan error,
)

ReceiveCaptions subscribes to captions and opens a stream of them. The subscription covers every flow in the session that has captioning enabled.

Captions are delivered on the returned channel until the stream ends, the session ends, or ctx is cancelled. Any error is reported on the returned error channel. The DeviceUID of each Caption identifies the audio stream it came from.

Captions include both partial and final messages, distinguished by IsPartial. While a phrase is being spoken, several partial messages refine the text, followed by one final message when the phrase is complete.

The Timecode is the position of the caption within the audio stream, measured from the moment captioning started on that flow.

Some fields depend on the provider. In particular, speaker identification (Speaker) is only populated by providers that support it, and is otherwise left empty.

This call aggregates the underlying subscribe, receive, and unsubscribe requests. By the time it returns, the subscription is either established or has failed. On success the returned channels are open and every caption produced after the return is guaranteed to be delivered; on failure the error channel already holds the error and both channels are already closed.

If the stream later fails, the error is sent on the error channel and both channels are closed, so the caller must select on both channels. Cancelling ctx unsubscribes and closes both channels, reporting the cancellation as ErrRequestCanceled on the error channel.

func (*EngineClient) ListDevices 

func (cl *EngineClient) ListDevices(ctx context.Context) (
    result []vsapi.Device, err error,
)

ListDevices lists the available audio devices.

Returns the current input and output devices, each described by a Device. Exactly one input device and one output device are marked with DeviceFeatureDefault, indicating the current system default for that direction.

func (*EngineClient) ReceiveEvents 

func (cl *EngineClient) ReceiveEvents(ctx context.Context) (
    <-chan vsapi.Event, <-chan error,
)

ReceiveEvents subscribes to engine events and opens a stream of them.

Events are delivered on the returned channel until the stream ends, the session ends, or ctx is cancelled. Any error is reported on the returned error channel. Each Event reports a single change through its Code; the application then reads the new state through the relevant call.

This call aggregates the underlying subscribe, receive, and unsubscribe requests. By the time it returns, the subscription is either established or has failed. On success the returned channels are open and every event produced after the return is guaranteed to be delivered; on failure the error channel already holds the error and both channels are already closed.

If the stream later fails, the error is sent on the error channel and both channels are closed, so the caller must select on both channels. Cancelling ctx unsubscribes and closes both channels, reporting the cancellation as ErrRequestCanceled on the error channel.

type EngineConfig

EngineConfig configures an EngineClient. The zero value is valid: every unset field falls back to the default documented on it.

type EngineConfig struct {
    // Address is the gRPC address of the engine, e.g. "127.0.0.1:52731".
    // If empty, the engine is auto-detected via DefaultEngine.
    Address string

    // ConnectMode selects the behavior when UserName is not the active OS user.
    // Defaults to ConnectWaitUser.
    ConnectMode ConnectMode
    // UserName is the OS user the session is opened for. If empty, the current
    // process user is used.
    UserName string

    // ConnectTimeout bounds establishing the connection and opening the session.
    // Zero selects DefaultConnectTimeout; NoTimeout or negative waits
    // indefinitely.
    ConnectTimeout time.Duration
    // RequestTimeout bounds a single request to the engine. Zero selects
    // DefaultRequestTimeout; NoTimeout or negative waits indefinitely.
    RequestTimeout time.Duration
    // CloseTimeout bounds closing the client and its session. Zero, NoTimeout,
    // or negative selects DefaultCloseTimeout, because a blocked Close cannot be
    // canceled, and timeout is the only way to interrupt it.
    CloseTimeout time.Duration
}

type EngineMetadata

EngineMetadata describes a running engine, parsed from its metadata file.

type EngineMetadata struct {
    // Edition is the human-readable edition title, e.g. "ViveEngine (Shared)".
    Edition string `json:"edition"`
    // Identifier is the reverse-DNS engine identifier, derived from the metadata filename.
    Identifier string `json:"identifier"`
    // Version is the engine version, e.g. "1.1.92".
    Version string `json:"version"`
    // RpcAddress is the gRPC address of the engine, e.g. "127.0.0.1:52731".
    RpcAddress string `json:"rpc_address"`
}

func DefaultEngine 

func DefaultEngine() (EngineMetadata, error)

DefaultEngine selects the default engine to connect to.

Selection rule: if the shared engine edition is present, it is selected; otherwise fails with ErrEngineNotDiscovered.

func DiscoverEngines 

func DiscoverEngines() ([]EngineMetadata, error)

DiscoverEngines finds all engine metadata files on the system and returns info about each running engine. Returns an empty slice if none are found.

type Error

Error is the umbrella interface satisfied by every error returned by the vsctl client. Every sentinel below satisfies Error and exactly one of the six error categories:

Callers can branch at three levels:

  • umbrella, to detect any vsctl error:

var vsErr vsctl.Error if errors.As(err, &vsErr) { ... }

  • category, to detect a class of failures:

var connErr vsctl.ConnectionError if errors.As(err, &connErr) { ... }

  • instance, to detect a specific error:

if errors.Is(err, vsctl.ErrEngineUnavailable) { ... }

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

type LifecycleError

LifecycleError indicates that the request was terminated locally before the engine responded (client closed, client-side timeout elapsed, or caller's context canceled). This is not an engine verdict.

Values:

Example:

var lifeErr vsctl.LifecycleError
if errors.As(err, &lifeErr) { ... }

type LifecycleError interface {
    Error
    // contains filtered or unexported methods
}

type RequestError

RequestError indicates that the request reached the engine and was rejected by it, for example because it was ill-formed or not permitted.

Values:

Example:

var reqErr vsctl.RequestError
if errors.As(err, &reqErr) { ... }

type RequestError interface {
    Error
    // contains filtered or unexported methods
}

type RuntimeError

RuntimeError indicates that the engine failed while handling the request, as opposed to rejecting it. The client is typically recommended to retry.

Values:

Example:

var rtErr vsctl.RuntimeError
if errors.As(err, &rtErr) { ... }

type RuntimeError interface {
    Error
    // contains filtered or unexported methods
}