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.

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.

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.

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	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	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”).