client

package
v1.8.0 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package client is a thin, ready-to-use gRPC client for the LabManager agent. It handles connection setup and mutual TLS so a caller (e.g. the control plane) only imports this package and calls the typed LabManager RPCs.

Ported from the legacy agent's client wrapper, adapted to the LabManager contract and to mTLS (the LabManager agent authenticates callers by client certificate + CN allowlist, not a JWT token).

Index

Constants

View Source
const (
	MaxMessageSize = 64 << 20
	MaxRequestSize = 4 << 20
	MaxItems       = 5000
)

MaxMessageSize is the largest answer the client accepts, equal to the agent's send limit; MaxRequestSize is the largest request it sends, equal to what the agent reads (a bigger one is refused locally); MaxItems is the most items one call may carry.

View Source
const (
	StopSnapshotMode_STOP_SNAPSHOT_MODE_UNSPECIFIED = protobuf.StopSnapshotMode_STOP_SNAPSHOT_MODE_UNSPECIFIED
	StopSnapshotMode_STOP_SNAPSHOT_MODE_SKIP        = protobuf.StopSnapshotMode_STOP_SNAPSHOT_MODE_SKIP
	StopSnapshotMode_STOP_SNAPSHOT_MODE_REQUIRED    = protobuf.StopSnapshotMode_STOP_SNAPSHOT_MODE_REQUIRED
)
View Source
const (
	ContractMajor = 1
	ContractMinor = 4
)

The API contract of the management agent, "major.minor", is what a caller needs to be compatible with an agent; the image tag says nothing about it (a patch release of the laboratory that touches no call must not stop the daemon).

  • A minor is bumped for every additive change of agent.proto (a field, a message, an RPC, an error reason).
  • The major is bumped for a change that breaks an existing caller.
  • A caller built against contract A.B works with an agent of contract C.D when C == A and D >= B (see Compatible).

pkg/agent/protobuf/contract.lock holds the version and a fingerprint of agent.proto's descriptor; TestContractLock fails when the proto changed without a new version, which forces the bump to be made deliberately. The agent reports the version in GetFeatures (contract_version) and the agent image carries it as the label com.cybericebox.laboratory.api-contract.

View Source
const (
	// ReasonReservationRequired: a LabGroup or Lab without reservation_id.
	ReasonReservationRequired = "RESERVATION_REQUIRED"
	// ReasonReservationNotFound: no reservation with that id in the caller's tenant.
	ReasonReservationNotFound = "RESERVATION_NOT_FOUND"
	// ReasonReservationEnded: the reservation takes no more work (ended, being deleted, past its end, or its tenant is
	// gone).
	ReasonReservationEnded = "RESERVATION_ENDED"
	// ReasonReservationFull: the item does not fit the rest of the reservation ("not enough room in this reservation").
	// Retryable: room may come back.
	ReasonReservationFull = "RESERVATION_FULL"
	// ReasonReservationMismatch: the item's deploy group already runs under another reservation, or an object that has a
	// reservation would be moved to another one.
	ReasonReservationMismatch = "RESERVATION_MISMATCH"
	// ReasonOverQuota: the tenant's overlapping reservations would peak above its quota.
	ReasonOverQuota = "OVER_QUOTA"
)

Reasons of a FAILED ItemResult (ItemResult.reason) for the reservation rules. Every other failure has an empty reason and only the error text.

View Source
const (
	// ReasonStaleLabReplacing: the name was taken by a Lab of an older generation (an older creation operation of the
	// same tenant and group); the agent has started deleting it. Retryable: repeat the same create until it succeeds.
	ReasonStaleLabReplacing = "STALE_LAB_REPLACING"
	// ReasonLabNameConflict: the name is taken by a Lab the agent will not replace on its own (a newer or an unrelated
	// generation, or no generation to compare). Not retryable; the caller must delete the Lab or choose another name.
	ReasonLabNameConflict = "LAB_NAME_CONFLICT"
)

Reasons of a FAILED Lab create item whose name is taken by a Lab of another generation.

View Source
const (
	ProfileContainer = "container"
	ProfileMicroVM   = "microvm"
	// ProfileVM is reserved: the agent refuses it.
	ProfileVM = "vm"
)

Device profiles (devices[].profile of a lab spec; empty is container).

View Source
const (
	// ReasonProfileUnsupported: the profile is vm, unknown, or switched off in this laboratory. Not retryable.
	ReasonProfileUnsupported = "PROFILE_UNSUPPORTED"
	// ReasonProfileUnavailable: the profile is supported but no running node can run it, and no autoscaler node group is
	// known to add one (CapacityResponse.node_profiles: available_now false and not available_after_scale_up).
	// Not retryable now.
	ReasonProfileUnavailable = "PROFILE_UNAVAILABLE"
)

Reasons of a FAILED Lab create item whose devices ask for a profile that cannot run.

View Source
const (
	// ErrorDomain is the errdetails.ErrorInfo domain of agent-specific errors.
	ErrorDomain = "agent.cybericebox"
	// ReasonTerminating is the ErrorInfo reason of a write refused because the
	// object with that deterministic name is still being deleted (finalizers run
	// asynchronously). The write was NOT applied; retry after a short delay.
	ReasonTerminating = "TERMINATING"
)
View Source
const ReasonCountMismatch = "COUNT_MISMATCH"

ReasonCountMismatch is the ErrorInfo reason of a selector call refused because more objects matched than the call's expected_count. Nothing was done.

View Source
const ReasonLabNotInGroup = "LAB_NOT_IN_GROUP"

ReasonLabNotInGroup: an access policy names Labs that are not in the LabGroup (removed, never created, or of another group). Not retryable. The text lists every such lab id as `lab "id"` / `labs "id1", "id2"`; the caller drops them from the policy and sends it again.

View Source
const ReasonPersistenceUnavailable = "PERSISTENCE_UNAVAILABLE"

ReasonPersistenceUnavailable: the lab asks for state persistence (devices[].persistence.enabled) and the lab nodes do not confirm that they can keep it (GetFeatures: state_persistence.available false, with an unavailable_reason). Nothing is created or started; the text carries only the fixed reason (`<CODE>:<n>/<m>`). Not retryable until the cluster is repaired.

View Source
const ReasonUnsupported = "UNSUPPORTED"

ReasonUnsupported: the agent does not advertise the capability the call needs (GetFeatures.lifecycle: per_lab_stop for StopLabs, retained_restart for StartLabs, full_group_stop for StopLabGroups and StartLabGroups). Not retryable; nothing was changed. The caller must check the capability before it dispatches.

Variables

View Source
var ContractVersion = fmt.Sprintf("%d.%d", ContractMajor, ContractMinor)

ContractVersion is the contract of this build of the SDK.

Functions

func Compatible added in v1.8.0

func Compatible(built, agent string) (bool, error)

Compatible says whether a caller built against contract `built` can use an agent that reports contract `agent`. An empty `agent` (an agent older than the field) is compatible only with a caller built against 1.0.

func CountMismatch

func CountMismatch(err error) (actual int, ok bool)

CountMismatch reports whether err is the agent's expected_count refusal (codes.FailedPrecondition + reason COUNT_MISMATCH) and the actual number of objects the selector matched.

func CreationDefinitionHash added in v1.1.0

func CreationDefinitionHash(specJSON []byte, group string, after []string) (string, error)

CreationDefinitionHash binds immutable dispatch evidence to the exact JSON definition before Create. Lifecycle is separate mutable intent; environment values and labels never enter this public fingerprint.

func IsTerminating

func IsTerminating(err error) bool

IsTerminating reports whether err is the agent's retryable "object is still being deleted" refusal (codes.Unavailable + ErrorInfo reason TERMINATING). The object's deletion is finished once Get* returns codes.NotFound.

Types

type Client

type Client interface {
	protobuf.LabManagerClient
	Close() error
}

Client is the typed LabManager client plus connection ownership.

func NewConnection

func NewConnection(config Config) (Client, error)

NewConnection dials the LabManager agent and returns a typed client. The caller owns the connection and must Close it. grpc.NewClient is lazy — the actual connection is established on the first RPC.

type Config

type Config struct {
	// Endpoint is the agent address, host:port. Dial the agent by its
	// certificate hostname (the agent's domain): gRPC then uses that as the
	// TLS SNI and verifies it against the server certificate SAN, so no
	// separate server-name setting is needed.
	Endpoint string
	TLS      TLS
}

Config describes how to reach a LabManager agent.

type GroupLifecycleSpec added in v1.1.0

type GroupLifecycleSpec = protobuf.GroupLifecycleSpec

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type GroupPodFormula added in v1.1.0

type GroupPodFormula = protobuf.GroupPodFormula

Sizing v2 aliases describe validated profiles without selecting one or changing defaults.

type GroupPodsFeature added in v1.1.0

type GroupPodsFeature = protobuf.GroupPodsFeature

Sizing v2 aliases describe validated profiles without selecting one or changing defaults.

type GroupPodsSizingProfile added in v1.1.0

type GroupPodsSizingProfile = protobuf.GroupPodsSizingProfile

Sizing v2 aliases describe validated profiles without selecting one or changing defaults.

type GroupPodsSizingV2 added in v1.1.0

type GroupPodsSizingV2 = protobuf.GroupPodsSizingV2

Sizing v2 aliases describe validated profiles without selecting one or changing defaults.

type GroupRetirementTarget added in v1.1.0

type GroupRetirementTarget = protobuf.GroupRetirementTarget

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type GroupSizingInputs added in v1.1.0

type GroupSizingInputs = protobuf.GroupSizingInputs

Sizing v2 aliases describe validated profiles without selecting one or changing defaults.

type GroupTarget added in v1.1.0

type GroupTarget = protobuf.GroupTarget

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type GroupTrafficEnvelope added in v1.1.0

type GroupTrafficEnvelope = protobuf.GroupTrafficEnvelope

Sizing v2 aliases describe validated profiles without selecting one or changing defaults.

type LabLifecycleStatus added in v1.1.0

type LabLifecycleStatus = protobuf.LabLifecycleStatus

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type LabLifecycleTarget added in v1.1.0

type LabLifecycleTarget = protobuf.LabLifecycleTarget

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type LabRetirementTarget added in v1.1.0

type LabRetirementTarget = protobuf.LabRetirementTarget

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type LifecycleFeature added in v1.1.0

type LifecycleFeature = protobuf.LifecycleFeature

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type PodSize added in v1.1.0

type PodSize = protobuf.PodSize

Sizing v2 aliases describe validated profiles without selecting one or changing defaults.

type ResourceAllocation added in v1.1.0

type ResourceAllocation = protobuf.ResourceAllocation

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type ResourceAmounts added in v1.1.0

type ResourceAmounts = protobuf.ResourceAmounts

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type RetireLabGroupsRequest added in v1.1.0

type RetireLabGroupsRequest = protobuf.RetireLabGroupsRequest

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type RetireLabsRequest added in v1.1.0

type RetireLabsRequest = protobuf.RetireLabsRequest

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type RetirementStatus added in v1.1.0

type RetirementStatus = protobuf.RetirementStatus

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type StartLabGroupsRequest added in v1.1.0

type StartLabGroupsRequest = protobuf.StartLabGroupsRequest

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type StartLabsRequest added in v1.1.0

type StartLabsRequest = protobuf.StartLabsRequest

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type StopLabGroupItem added in v1.1.0

type StopLabGroupItem = protobuf.StopLabGroupItem

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type StopLabGroupsRequest added in v1.1.0

type StopLabGroupsRequest = protobuf.StopLabGroupsRequest

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type StopLabItem added in v1.1.0

type StopLabItem = protobuf.StopLabItem

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type StopLabsRequest added in v1.1.0

type StopLabsRequest = protobuf.StopLabsRequest

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type StopSnapshotMode added in v1.1.0

type StopSnapshotMode = protobuf.StopSnapshotMode

Lifecycle aliases expose the additive protocol through the public client. Client embeds LabManagerClient, including StopLabs and StartLabs.

type TLS

type TLS struct {
	Enabled  bool
	CertFile string // client certificate (PEM) presented for mTLS
	KeyFile  string // client private key (PEM)
	CAFile   string // CA (PEM) that signed the agent's server certificate; empty = system roots
}

TLS configures the transport. When Enabled, the connection is mutual TLS: the client presents CertFile/KeyFile (whose CN must be a Tenant) and verifies the server against CAFile, or against the system roots when CAFile is empty (a publicly trusted certificate). With no CertFile and KeyFile it is server-authenticated TLS only, for Enroll.

Jump to

Keyboard shortcuts

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