jumpstarter

jumpstarter.v1

Services

ControllerService

A service where an exporter can connect to make itself available.

Method	Request	Response	Description
Register	RegisterRequest	RegisterResponse	Register an exporter with the controller.
Unregister	UnregisterRequest	UnregisterResponse	Unregister an exporter from the controller. Disconnecting will invalidate any existing router tokens.
ReportStatus	ReportStatusRequest	ReportStatusResponse	Report exporter status to the controller.
Listen	ListenRequest	stream ListenResponse	Listen for incoming client connections on a lease. Returns stream tokens for accepting incoming client connections.
Status	StatusRequest	stream StatusResponse	Stream lease status updates for the exporter.
Dial	DialRequest	DialResponse	Dial an exporter through the router. Returns a stream token for connecting to the desired exporter. Leases are checked before token issuance.
GetLease	GetLeaseRequest	GetLeaseResponse	Retrieve a lease by name.
RequestLease	RequestLeaseRequest	RequestLeaseResponse	Request a new lease for an exporter.
ReleaseLease	ReleaseLeaseRequest	ReleaseLeaseResponse	Release an active lease.
ListLeases	ListLeasesRequest	ListLeasesResponse	List all leases.
GetServiceEndpoints	GetServiceEndpointsRequest	GetServiceEndpointsResponse	Discover optional service endpoints (e.g. telemetry). Exporters and clients call this after registration to find the telemetry service. Returns an empty list when no optional services are deployed. Older controllers return UNIMPLEMENTED; callers must treat that as an empty list.
UpdateLeaseHooks	UpdateLeaseHooksRequest	LeaseHooks	Record a lifecycle hook transition for the exporter’s lease. The record survives exporter restarts. Exporters start a hook only after the controller has stored it as running. Returns FAILED_PRECONDITION for a transition the record does not allow (for example a stale lease).
RotateToken	RotateTokenRequest	RotateTokenResponse	Rotate the authentication token for the exporter.

ExporterService

A service an exporter can share locally to be used without a server. Channel and call credentials are used to authenticate the client and route to the right exporter.

Method	Request	Response	Description
GetReport	google.protobuf.Empty	GetReportResponse	Retrieve the exporter driver report.
DriverCall	DriverCallRequest	DriverCallResponse	Invoke a method on a driver instance.
StreamingDriverCall	StreamingDriverCallRequest	stream StreamingDriverCallResponse	Invoke a streaming method on a driver instance.
LogStream	google.protobuf.Empty	stream LogStreamResponse	Stream log messages from the exporter.
Reset	ResetRequest	ResetResponse	Reset the exporter connection.
GetStatus	GetStatusRequest	GetStatusResponse	Retrieve the current exporter status.
EndSession	EndSessionRequest	EndSessionResponse	End the current session, triggering the afterLease hook. The client should keep the connection open to receive hook logs via LogStream. Returns after the afterLease hook completes.

Messages

RegisterRequest

Registration request sent by an exporter to the controller.

Field	Number	Type	Label	Description
labels	1	map<string, string>		Key-value metadata labels.
reports	2	DriverInstanceReport	repeated	Driver instance reports for this exporter.
records_lease_hooks	3	bool		The exporter records its lease hooks (UpdateLeaseHooks). The controller then holds it from new leases while its record owes an afterLease hook, whatever status it reports.

DriverInstanceReport

Report describing a single driver instance on an exporter.

Field	Number	Type	Label	Description
uuid	1	string		Unique identifier within the exporter.
parent_uuid	2	string	optional	Parent device UUID, if this is a child device.
labels	3	map<string, string>		Key-value metadata labels.
description	4	string	optional	Custom driver description for CLI display.
methods_description	5	map<string, string>		Method name to help text mapping for CLI.

RegisterResponse

Registration response returned by the controller.

Field	Number	Type	Label	Description
uuid	1	string		Assigned exporter UUID.

UnregisterRequest

Request to unregister an exporter from the controller.

Field	Number	Type	Label	Description
reason	2	string		Reason for unregistering.

UnregisterResponse

Response to an unregister request.

No fields defined.

ListenRequest

Request to listen for incoming client connections on a lease.

Field	Number	Type	Label	Description
lease_name	1	string		Name of the lease to listen on.

ListenResponse

Response containing router connection details for an incoming client.

Field	Number	Type	Label	Description
router_endpoint	1	string		The router gRPC endpoint URL.
router_token	2	string		Authentication token for the router.

StatusRequest

Request to subscribe to exporter lease status updates.

No fields defined.

StatusResponse

Lease status update for an exporter.

Field	Number	Type	Label	Description
leased	1	bool		Whether the exporter is currently leased.
lease_name	2	string	optional	Name of the active lease, if any.
client_name	3	string	optional	Name of the connected client, if any.
context	4	map<string, string>		User-defined lease context metadata.
lease_hooks	5	LeaseHooks		Hook record of the exporter’s latest lease. Always set by controllers that keep it, even when empty.
lease_uid	6	string	optional	UID of the active lease, if any. Tells it apart from an earlier lease with the same name.

LeaseHookState

State of one lease lifecycle hook.

Field	Number	Type	Label	Description
phase	1	LeaseHookPhase		Phase of the hook.
on_failure	2	LeaseHookFailureAction		Failure action configured when the hook ran.
message	3	string		Failure or skip reason, if any.
attempts	4	uint32		Times the hook was started

LeaseHooks

Lifecycle hook record of an exporter’s latest lease, kept by the controller.

Field	Number	Type	Label	Description
lease_name	1	string		Lease the record belongs to
before_lease	2	LeaseHookState		beforeLease hook
after_lease	3	LeaseHookState		afterLease hook
lease_uid	4	string		UID of the lease the record belongs to. A lease name can be reused once the lease is deleted.
client_name	5	string		Client that held the lease, for hooks that run after the lease has ended.

UpdateLeaseHooksRequest

Request to record a lifecycle hook transition for a lease.

Field	Number	Type	Label	Description
lease_name	1	string		Lease the hook runs for.
before_lease	2	LeaseHookState	oneof hook	New beforeLease hook state.
after_lease	3	LeaseHookState	oneof hook	New afterLease hook state.
lease_uid	4	string		UID of the lease the hook runs for (required).

DialRequest

Request to dial an exporter through the router.

Field	Number	Type	Label	Description
lease_name	1	string		Name of the lease to connect through.

DialResponse

Response containing router connection details for the dialed exporter.

Field	Number	Type	Label	Description
router_endpoint	1	string		The router gRPC endpoint URL.
router_token	2	string		Authentication token for the router.

ReportStatusRequest

Request to report exporter status to the controller.

Field	Number	Type	Label	Description
status	1	ExporterStatus		Current exporter status.
message	2	string	optional	Optional human-readable status message.
release_lease	3	bool	optional	When true, controller should release the active lease.

ReportStatusResponse

Response to a status report request.

No fields defined.

GetReportResponse

Response containing the exporter driver report.

Field	Number	Type	Label	Description
uuid	1	string		Exporter UUID.
labels	2	map<string, string>		Key-value metadata labels.
reports	3	DriverInstanceReport	repeated	Driver instance reports.
alternative_endpoints	4	Endpoint	repeated	Alternative connection endpoints.
motd	5	string		Message of the day shown to clients when entering a shell.

Endpoint

Connection endpoint with TLS credentials.

Field	Number	Type	Label	Description
endpoint	1	string		The endpoint URL.
certificate	2	string		Server TLS certificate.
client_certificate	3	string		Client TLS certificate.
client_private_key	4	string		Client TLS private key.

DriverCallRequest

Request to invoke a method on a driver instance.

Field	Number	Type	Label	Description
uuid	1	string		UUID of the driver instance.
method	2	string		Method name to invoke.
args	3	google.protobuf.Value	repeated	Arguments for the method call.

DriverCallResponse

Response from a driver method invocation.

Field	Number	Type	Label	Description
uuid	1	string		UUID of the driver instance.
result	2	google.protobuf.Value		Return value from the method call.

StreamingDriverCallRequest

Request to invoke a streaming method on a driver instance.

Field	Number	Type	Label	Description
uuid	1	string		UUID of the driver instance.
method	2	string		Method name to invoke.
args	3	google.protobuf.Value	repeated	Arguments for the method call.

StreamingDriverCallResponse

Response from a streaming driver method invocation.

Field	Number	Type	Label	Description
uuid	1	string		UUID of the driver instance.
result	2	google.protobuf.Value		Return value from the method call.

LogStreamResponse

A log message from the exporter log stream.

Field	Number	Type	Label	Description
uuid	1	string		UUID of the driver instance.
severity	2	string		Log severity level.
message	3	string		Log message content.
source	4	LogSource	optional	Source of the log message.
driver_type	5	string	optional	Driver category when source=DRIVER (e.g. “power”, “storage”).
operation	6	string	optional	Operation name when the log is part of a known operation.
timestamp	7	google.protobuf.Timestamp	optional	Explicit timestamp of the log entry.
structured_fields	8	map<string, string>		Additional structured key-value fields.

ResetRequest

Request to reset the exporter connection.

No fields defined.

ResetResponse

Response to a reset request.

No fields defined.

GetLeaseRequest

Request to retrieve a lease by name.

Field	Number	Type	Label	Description
name	1	string		Name of the lease to retrieve.

GetLeaseResponse

Response containing lease details.

Field	Number	Type	Label	Description
duration	1	google.protobuf.Duration		Requested lease duration.
selector	2	LabelSelector		Label selector for matching exporters.
begin_time	3	google.protobuf.Timestamp	optional	Lease start time, if active.
end_time	4	google.protobuf.Timestamp	optional	Lease end time, if active.
exporter_uuid	5	string	optional	UUID of the assigned exporter, if any.
conditions	6	Condition	repeated	Lease status conditions.

RequestLeaseRequest

Request to create a new lease for an exporter.

Field	Number	Type	Label	Description
duration	1	google.protobuf.Duration		Desired lease duration.
selector	2	LabelSelector		Label selector for matching exporters.

RequestLeaseResponse

Response containing the name of the created lease.

Field	Number	Type	Label	Description
name	1	string		Name of the created lease.

ReleaseLeaseRequest

Request to release an active lease.

Field	Number	Type	Label	Description
name	1	string		Name of the lease to release.

ReleaseLeaseResponse

Response to a release lease request.

No fields defined.

ListLeasesRequest

Request to list all leases.

No fields defined.

ListLeasesResponse

Response containing the list of lease names.

Field	Number	Type	Label	Description
names	1	string	repeated	Names of all leases.

GetStatusRequest

Request to retrieve the current exporter status.

No fields defined.

GetStatusResponse

Response containing the current exporter status.

Field	Number	Type	Label	Description
status	1	ExporterStatus		Current exporter status.
message	2	string	optional	Human-readable status message.
status_version	3	uint64		Monotonic counter, increments on each status change.
previous_status	4	ExporterStatus	optional	Previous status for transition tracking.

EndSessionRequest

Request to end the current exporter session.

No fields defined.

EndSessionResponse

Response to an end session request.

Field	Number	Type	Label	Description
success	1	bool		Whether the session ended successfully.
message	2	string	optional	Human-readable result message.

GetServiceEndpointsRequest

Request to discover optional service endpoints.

No fields defined.

GetServiceEndpointsResponse

Response containing optional service endpoint addresses.

Field	Number	Type	Label	Description
telemetry_endpoints	1	TelemetryEndpoint	repeated	Empty when no optional services (e.g. telemetry) are deployed.

TelemetryEndpoint

Address of an optional telemetry service endpoint.

Field	Number	Type	Label	Description
endpoint	1	string		gRPC address (host:port).
certificate	2	string		Optional CA certificate PEM for TLS verification.
min_severity	3	string		Minimum log severity to forward (e.g. “info”, “warning”).
token	4	string		Bearer token for TelemetryService calls, naming the caller’s exporter or client. It is valid only for telemetry and never outlives the credential that requested it. Call GetServiceEndpoints again for a new one before token_expiry.
token_expiry	5	google.protobuf.Timestamp		When token expires.

RotateTokenRequest

Request to rotate the authentication token for an exporter.

No fields defined.

RotateTokenResponse

Response containing the newly rotated token.

Field	Number	Type	Label	Description
token	1	string		The new authentication token.
expiry	2	google.protobuf.Timestamp		The expiration time of the new token.

Enums

LeaseHookPhase

Phase of a lease lifecycle hook.

Name	Number	Description
LEASE_HOOK_PHASE_UNSPECIFIED	0	Not started.
LEASE_HOOK_PHASE_RUNNING	1	Started
LEASE_HOOK_PHASE_SUCCEEDED	2	Finished successfully.
LEASE_HOOK_PHASE_FAILED	3	Failed
LEASE_HOOK_PHASE_SKIPPED	4	Not run (not configured, or not needed for this lease).

LeaseHookFailureAction

Failure action configured for a lease lifecycle hook (onFailure).

Name	Number	Description
LEASE_HOOK_FAILURE_ACTION_UNSPECIFIED	0
LEASE_HOOK_FAILURE_ACTION_WARN	1	Continue and warn.
LEASE_HOOK_FAILURE_ACTION_END_LEASE	2	End the lease.
LEASE_HOOK_FAILURE_ACTION_EXIT	3	End the lease and take the exporter offline.