Documentation
¶
Overview ¶
Package api defines canonical domain-level DTO types for shared API payloads. These types are the authoritative definitions for wire shapes that cross the server/client/cli boundary. Handlers encode them; clients and CLI decode them.
Ownership rules:
- Types here are stable across server, client, and CLI boundaries.
- JSON field names must not change without a coordinated wire-format migration.
- Handler-local and CLI-local mirrors of these shapes are superseded by this package.
Index ¶
- type APITokenListItem
- type APITokenListResponse
- type CreateAPITokenRequest
- type CreateAPITokenResponse
- type CreateBootstrapTokenRequest
- type CreateBootstrapTokenResponse
- type CreateMigRunRequest
- type CreateSingleRepoRunResponse
- type DiffListItem
- type DiffListResponse
- type GlobalEnvListItem
- type GlobalEnvPutRequest
- type GlobalEnvResponse
- type JobListItem
- type JobListResponse
- type JobStatusResponse
- type MigArchiveResponse
- type MigListResponse
- type MigRepoImportError
- type MigRepoImportResponse
- type MigRepoListResponse
- type MigRepoSelector
- type MigRepoSummary
- type MigSummary
- type NamedSpecCatalogEntry
- type NamedSpecListResponse
- type Node
- type NodeClaimResponse
- type NodeDiagnostic
- type NodeHeartbeatRequest
- type PullResolutionResponse
- type RunBuildGateForcedOverrides
- type RunBuildGateForcedStack
- type RunRestartRequest
- type RunSpecOverrides
- type RunSubmitRequest
- type WaveSummary
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APITokenListItem ¶
type APITokenListItem struct {
TokenID string `json:"token_id"`
Role string `json:"role"`
Username *string `json:"username,omitempty"`
Description *string `json:"description,omitempty"`
IssuedAt time.Time `json:"issued_at"`
ExpiresAt time.Time `json:"expires_at"`
LastUsedAt *time.Time `json:"last_used_at,omitempty"`
RevokedAt *time.Time `json:"revoked_at,omitempty"`
CreatedBy *string `json:"created_by,omitempty"`
}
APITokenListItem is one API token in the list response.
type APITokenListResponse ¶
type APITokenListResponse struct {
Tokens []APITokenListItem `json:"tokens"`
}
APITokenListResponse is the canonical response from GET /v1/tokens.
type CreateAPITokenRequest ¶
type CreateAPITokenRequest struct {
Role string `json:"role"`
Username string `json:"username,omitempty"`
Description string `json:"description,omitempty"`
ExpiresInDays int `json:"expires_in_days"`
}
CreateAPITokenRequest is the canonical request for POST /v1/tokens.
type CreateAPITokenResponse ¶
type CreateAPITokenResponse struct {
Token string `json:"token"`
TokenID string `json:"token_id"`
Role string `json:"role"`
Username *string `json:"username,omitempty"`
ExpiresAt time.Time `json:"expires_at"`
Warning string `json:"warning"`
}
CreateAPITokenResponse is the canonical response from POST /v1/tokens.
type CreateBootstrapTokenRequest ¶
type CreateBootstrapTokenRequest struct {
NodeID domaintypes.NodeID `json:"node_id"`
ExpiresInMinutes int `json:"expires_in_minutes"`
}
CreateBootstrapTokenRequest is the canonical request for POST /v1/bootstrap/tokens.
type CreateBootstrapTokenResponse ¶
type CreateBootstrapTokenResponse struct {
Token string `json:"token"`
NodeID domaintypes.NodeID `json:"node_id"`
ExpiresAt time.Time `json:"expires_at"`
}
CreateBootstrapTokenResponse is the canonical response from POST /v1/bootstrap/tokens.
type CreateMigRunRequest ¶ added in v0.1.16
type CreateMigRunRequest struct {
RepoSelector MigRepoSelector `json:"repo_selector"`
CreatedBy *string `json:"created_by,omitempty"`
GitLabToken *string `json:"gitlab_token,omitempty"`
}
type CreateSingleRepoRunResponse ¶
type CreateSingleRepoRunResponse struct {
WaveID domaintypes.WaveID `json:"wave_id"`
RunID domaintypes.RunID `json:"run_id"`
MigID domaintypes.MigID `json:"mig_id"`
SpecID domaintypes.SpecID `json:"spec_id"`
}
CreateSingleRepoRunResponse is returned by POST /v1/runs.
type DiffListItem ¶
type DiffListResponse ¶
type DiffListResponse struct {
Diffs []DiffListItem `json:"diffs"`
}
type GlobalEnvListItem ¶
type GlobalEnvPutRequest ¶
type GlobalEnvResponse ¶
type JobListItem ¶
type JobListItem struct {
JobID types.JobID `json:"job_id"`
Name string `json:"name"`
JobType types.JobType `json:"job_type"`
Status types.JobStatus `json:"status"`
DurationMs int64 `json:"duration_ms"`
JobImage string `json:"job_image"`
NodeID *types.NodeID `json:"node_id"`
MigName string `json:"mig_name"`
RunID types.RunID `json:"run_id"`
RepoID types.RepoID `json:"repo_id"`
}
type JobListResponse ¶
type JobListResponse struct {
Jobs []JobListItem `json:"jobs"`
Total int64 `json:"total"`
}
type JobStatusResponse ¶
type JobStatusResponse struct {
JobID types.JobID `json:"job_id"`
RunID types.RunID `json:"run_id"`
RepoID types.RepoID `json:"repo_id"`
Attempt int32 `json:"attempt"`
Name string `json:"name"`
JobType types.JobType `json:"job_type"`
Status types.JobStatus `json:"status"`
JobImage string `json:"job_image"`
NodeID *types.NodeID `json:"node_id"`
ExitCode *int32 `json:"exit_code"`
StartedAt *time.Time `json:"started_at"`
FinishedAt *time.Time `json:"finished_at"`
DurationMs int64 `json:"duration_ms"`
RepoShaIn string `json:"repo_sha_in"`
RepoShaOut string `json:"repo_sha_out"`
RepoShaIn8 string `json:"repo_sha_in8"`
RepoShaOut8 string `json:"repo_sha_out8"`
}
type MigArchiveResponse ¶
type MigArchiveResponse struct {
ID domaintypes.MigID `json:"id"`
Name string `json:"name"`
Archived bool `json:"archived"`
}
type MigListResponse ¶
type MigListResponse struct {
Migs []MigSummary `json:"migs"`
}
MigListResponse is the canonical response envelope for GET /v1/migs.
type MigRepoImportError ¶
MigRepoImportError identifies one failed CSV input line.
type MigRepoImportResponse ¶
type MigRepoImportResponse struct {
Created int `json:"created"`
Updated int `json:"updated"`
Failed int `json:"failed"`
Errors []MigRepoImportError `json:"errors"`
}
MigRepoImportResponse reports the result of a bulk repository import.
type MigRepoListResponse ¶
type MigRepoListResponse struct {
Repos []MigRepoSummary `json:"repos"`
}
MigRepoListResponse is the canonical response envelope for GET /v1/migs/{id}/repos.
type MigRepoSelector ¶ added in v0.1.16
type MigRepoSelector struct {
Mode string `json:"mode"`
Repos []domaintypes.RepoURL `json:"repos,omitempty"`
}
type MigRepoSummary ¶
type MigRepoSummary struct {
ID domaintypes.MigRepoID `json:"id"`
MigID domaintypes.MigID `json:"mig_id"`
RepoURL string `json:"repo_url"`
BaseRef string `json:"base_ref"`
CreatedAt time.Time `json:"created_at"`
}
MigRepoSummary is the canonical DTO for a single repo entry within a mig's repo set. It is the authoritative response shape for:
- GET /v1/migs/{id}/repos — individual items in the repo list
- POST /v1/migs/{id}/repos — the added repo in the 201 response
Wire shape is stable: JSON field names must not change.
type MigSummary ¶
type MigSummary struct {
ID domaintypes.MigID `json:"id"`
Name string `json:"name"`
SpecID *domaintypes.SpecID `json:"spec_id,omitempty"`
CreatedBy *string `json:"created_by,omitempty"`
Archived bool `json:"archived"`
CreatedAt time.Time `json:"created_at"`
}
MigSummary is the canonical DTO for a single mig project entry. It is the authoritative response shape for:
- GET /v1/migs — individual items in the mig list
- POST /v1/migs — the created mig in the 201 response
Wire shape is stable: JSON field names must not change.
type NamedSpecCatalogEntry ¶
type NamedSpecCatalogEntry struct {
Name string `json:"name"`
Description string `json:"description"`
Source string `json:"source"`
Path string `json:"path"`
SHA string `json:"sha"`
}
NamedSpecCatalogEntry identifies a named spec discovered from a Git repository.
type NamedSpecListResponse ¶
type NamedSpecListResponse struct {
Specs []NamedSpecCatalogEntry `json:"specs"`
}
NamedSpecListResponse is returned by GET /v1/specs.
type Node ¶
type Node struct {
ID types.NodeID `json:"id"`
Name string `json:"name"`
IPAddress string `json:"ip_address"`
Version *string `json:"version,omitempty"`
Concurrency int32 `json:"concurrency"`
CPUTotalMillis int32 `json:"cpu_total_millis"`
CPUFreeMillis int32 `json:"cpu_free_millis"`
MemTotalBytes int64 `json:"mem_total_bytes"`
MemFreeBytes int64 `json:"mem_free_bytes"`
DiskTotalBytes int64 `json:"disk_total_bytes"`
DiskFreeBytes int64 `json:"disk_free_bytes"`
CertSerial *string `json:"cert_serial,omitempty"`
CertFingerprint *string `json:"cert_fingerprint,omitempty"`
CertNotBefore *string `json:"cert_not_before,omitempty"`
CertNotAfter *string `json:"cert_not_after,omitempty"`
LastHeartbeat *string `json:"last_heartbeat,omitempty"`
DrainRevision int64 `json:"drain_revision"`
DrainOwner *string `json:"drain_owner"`
Drained bool `json:"drained"`
CreatedAt string `json:"created_at"`
}
type NodeClaimResponse ¶
type NodeClaimResponse struct {
ResumeCount int `json:"resume_count,omitempty"`
RunID types.RunID `json:"id"`
Name *string `json:"name,omitempty"`
RepoID types.RepoID `json:"repo_id"`
Attempt int32 `json:"attempt"`
JobID types.JobID `json:"job_id"`
JobName string `json:"job_name"`
JobType types.JobType `json:"job_type"`
JobImage string `json:"job_image"`
NextID *types.JobID `json:"next_id"`
RepoURL types.RepoURL `json:"repo_url"`
Status types.RunStatus `json:"status"`
NodeID types.NodeID `json:"node_id"`
BaseRef types.GitRef `json:"base_ref"`
CommitSHA types.CommitSHA `json:"commit_sha,omitempty"`
RepoSHAIn types.CommitSHA `json:"repo_sha_in,omitempty"`
StartedAt string `json:"started_at"`
CreatedAt string `json:"created_at"`
Spec json.RawMessage `json:"spec,omitempty"`
MigContext *contracts.MigClaimContext `json:"mig_context,omitempty"`
GateContext *contracts.GateClaimContext `json:"gate_context,omitempty"`
DetectedStack *contracts.StackExpectation `json:"detected_stack,omitempty"`
}
NodeClaimResponse is the control-plane contract returned to a node after a successful claim.
type NodeDiagnostic ¶
type NodeDiagnostic struct {
NodeID types.NodeID `json:"node_id"`
Component string `json:"component"`
Status string `json:"status"`
LastError *string `json:"last_error,omitempty"`
Version *string `json:"version,omitempty"`
ImageRef *string `json:"image_ref,omitempty"`
LocalImageID *string `json:"local_image_id,omitempty"`
RemoteImageID *string `json:"remote_image_id,omitempty"`
Details json.RawMessage `json:"details"`
LastCheckedAt *string `json:"last_checked_at,omitempty"`
LastSuccessAt *string `json:"last_success_at,omitempty"`
UpdatedAt string `json:"updated_at"`
}
type NodeHeartbeatRequest ¶
type NodeHeartbeatRequest struct {
CPUFreeMillis int64 `json:"cpu_free_millis"`
CPUTotalMillis int64 `json:"cpu_total_millis"`
MemFreeBytes int64 `json:"mem_free_bytes"`
MemTotalBytes int64 `json:"mem_total_bytes"`
DiskFreeBytes int64 `json:"disk_free_bytes"`
DiskTotalBytes int64 `json:"disk_total_bytes"`
Version string `json:"version,omitempty"`
}
NodeHeartbeatRequest is the node-to-control-plane resource snapshot. CPU fields stay wide enough for the server to reject overflow before narrowing.
type PullResolutionResponse ¶
type RunBuildGateForcedOverrides ¶
type RunBuildGateForcedOverrides struct {
Pre *RunBuildGateForcedStack `json:"pre,omitempty"`
Post *RunBuildGateForcedStack `json:"post,omitempty"`
}
type RunBuildGateForcedStack ¶
type RunRestartRequest ¶ added in v0.1.16
type RunSpecOverrides ¶
type RunSpecOverrides struct {
StepEnvs map[string][]string `json:"step_envs,omitempty"`
BuildGateForced *RunBuildGateForcedOverrides `json:"build_gate_forced,omitempty"`
}
RunSpecOverrides contains mutations that the server applies only to a named spec after it compiles the selected repository source.
type RunSubmitRequest ¶
type RunSubmitRequest struct {
RepoURL domaintypes.RepoURL `json:"repo_url"`
Ref domaintypes.GitRef `json:"ref"`
CommitSHA string `json:"commit_sha,omitempty"`
Spec json.RawMessage `json:"spec,omitempty"`
SpecSelector string `json:"spec_selector,omitempty"`
SpecOverrides *RunSpecOverrides `json:"spec_overrides,omitempty"`
CreatedBy string `json:"created_by,omitempty"`
GitLabToken *string `json:"gitlab_token,omitempty"`
}
RunSubmitRequest is the canonical request DTO for POST /v1/runs. It is the authoritative shape for single-repo run submission shared between the server handler and CLI clients.
Wire shape is stable: JSON field names must not change.
type WaveSummary ¶
type WaveSummary struct {
ID domaintypes.WaveID `json:"id"`
MigID domaintypes.MigID `json:"mig_id"`
SpecID domaintypes.SpecID `json:"spec_id"`
CreatedBy *string `json:"created_by,omitempty"`
Status domaintypes.WaveStatus `json:"status"`
CreatedAt string `json:"created_at"`
StartedAt *string `json:"started_at,omitempty"`
FinishedAt *string `json:"finished_at,omitempty"`
Counts *domaintypes.RunCounts `json:"run_counts,omitempty"`
}