# jumpstarter

`jumpstarter.v1`

## Services

### ControllerService

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

| Method | Request | Response | Description |
| --- | --- | --- | --- |
| `Register` | [`RegisterRequest`](jumpstarter.md#registerrequest) | [`RegisterResponse`](jumpstarter.md#registerresponse) | Register an exporter with the controller. |
| `Unregister` | [`UnregisterRequest`](jumpstarter.md#unregisterrequest) | [`UnregisterResponse`](jumpstarter.md#unregisterresponse) | Unregister an exporter from the controller. Disconnecting will invalidate any existing router tokens. |
| `ReportStatus` | [`ReportStatusRequest`](jumpstarter.md#reportstatusrequest) | [`ReportStatusResponse`](jumpstarter.md#reportstatusresponse) | Report exporter status to the controller. |
| `Listen` | [`ListenRequest`](jumpstarter.md#listenrequest) | stream [`ListenResponse`](jumpstarter.md#listenresponse) | Listen for incoming client connections on a lease. Returns stream tokens for accepting incoming client connections. |
| `Status` | [`StatusRequest`](jumpstarter.md#statusrequest) | stream [`StatusResponse`](jumpstarter.md#statusresponse) | Stream lease status updates for the exporter. |
| `Dial` | [`DialRequest`](jumpstarter.md#dialrequest) | [`DialResponse`](jumpstarter.md#dialresponse) | Dial an exporter through the router. Returns a stream token for connecting to the desired exporter. Leases are checked before token issuance. |
| `AuditStream` | stream [`AuditStreamRequest`](jumpstarter.md#auditstreamrequest) | `google.protobuf.Empty` | Stream audit events from the exporters. Audit events are used to track the exporter activity. |
| `GetLease` | [`GetLeaseRequest`](client.md#getleaserequest) | [`GetLeaseResponse`](jumpstarter.md#getleaseresponse) | Retrieve a lease by name. |
| `RequestLease` | [`RequestLeaseRequest`](jumpstarter.md#requestleaserequest) | [`RequestLeaseResponse`](jumpstarter.md#requestleaseresponse) | Request a new lease for an exporter. |
| `ReleaseLease` | [`ReleaseLeaseRequest`](jumpstarter.md#releaseleaserequest) | [`ReleaseLeaseResponse`](jumpstarter.md#releaseleaseresponse) | Release an active lease. |
| `ListLeases` | [`ListLeasesRequest`](client.md#listleasesrequest) | [`ListLeasesResponse`](client.md#listleasesresponse) | List all leases. |

### 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`](jumpstarter.md#getreportresponse) | Retrieve the exporter driver report. |
| `DriverCall` | [`DriverCallRequest`](jumpstarter.md#drivercallrequest) | [`DriverCallResponse`](jumpstarter.md#drivercallresponse) | Invoke a method on a driver instance. |
| `StreamingDriverCall` | [`StreamingDriverCallRequest`](jumpstarter.md#streamingdrivercallrequest) | stream [`StreamingDriverCallResponse`](jumpstarter.md#streamingdrivercallresponse) | Invoke a streaming method on a driver instance. |
| `LogStream` | `google.protobuf.Empty` | stream [`LogStreamResponse`](jumpstarter.md#logstreamresponse) | Stream log messages from the exporter. |
| `Reset` | [`ResetRequest`](jumpstarter.md#resetrequest) | [`ResetResponse`](jumpstarter.md#resetresponse) | Reset the exporter connection. |
| `GetStatus` | [`GetStatusRequest`](jumpstarter.md#getstatusrequest) | [`GetStatusResponse`](jumpstarter.md#getstatusresponse) | Retrieve the current exporter status. |
| `EndSession` | [`EndSessionRequest`](jumpstarter.md#endsessionrequest) | [`EndSessionResponse`](jumpstarter.md#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`](jumpstarter.md#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. |

### 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. |

### AuditStreamRequest

An audit event sent from an exporter to the controller.

| Field | Number | Type | Label | Description |
| --- | --- | --- | --- | --- |
| `exporter_uuid` | 1 | `string` |  | UUID of the exporter. |
| `driver_instance_uuid` | 2 | `string` |  | UUID of the driver instance. |
| `severity` | 3 | `string` |  | Severity level of the event. |
| `message` | 4 | `string` |  | Human-readable event message. |

### ReportStatusRequest

Request to report exporter status to the controller.

| Field | Number | Type | Label | Description |
| --- | --- | --- | --- | --- |
| `status` | 1 | [`ExporterStatus`](common.md#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`](jumpstarter.md#driverinstancereport) | repeated | Driver instance reports. |
| `alternative_endpoints` | 4 | [`Endpoint`](jumpstarter.md#endpoint) | repeated | Alternative connection endpoints. |

### 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`](common.md#logsource) | optional | Source of the log message. |

### 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`](kubernetes.md#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`](kubernetes.md#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`](kubernetes.md#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`](common.md#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`](common.md#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. |