api

package
v0.1.18-rc17 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 4 Imported by: 0

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

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 DiffListItem struct {
	ID        types.DiffID      `json:"id"`
	JobID     types.JobID       `json:"job_id"`
	CreatedAt time.Time         `json:"created_at"`
	Size      int               `json:"gzipped_size"`
	Summary   types.DiffSummary `json:"summary,omitempty"`
}

type DiffListResponse

type DiffListResponse struct {
	Diffs []DiffListItem `json:"diffs"`
}

type GlobalEnvListItem

type GlobalEnvListItem struct {
	Key    string `json:"key"`
	Value  string `json:"value,omitempty"`
	Target string `json:"target"`
	Secret bool   `json:"secret"`
}

type GlobalEnvPutRequest

type GlobalEnvPutRequest struct {
	Value  string `json:"value"`
	Target string `json:"target"`
	Secret *bool  `json:"secret,omitempty"`
}

type GlobalEnvResponse

type GlobalEnvResponse struct {
	Key    string `json:"key"`
	Value  string `json:"value"`
	Target string `json:"target"`
	Secret bool   `json:"secret"`
}

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

type MigRepoImportError struct {
	Line    int    `json:"line"`
	Message string `json:"message"`
}

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"`
	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 PullResolutionResponse struct {
	RunID           types.RunID  `json:"run_id"`
	RepoID          types.RepoID `json:"repo_id"`
	RepoURL         string       `json:"repo_url,omitempty"`
	SourceCommitSHA string       `json:"source_commit_sha,omitempty"`
}

type RunBuildGateForcedOverrides

type RunBuildGateForcedOverrides struct {
	Pre  *RunBuildGateForcedStack `json:"pre,omitempty"`
	Post *RunBuildGateForcedStack `json:"post,omitempty"`
}

type RunBuildGateForcedStack

type RunBuildGateForcedStack struct {
	Language string `json:"language"`
	Release  string `json:"release"`
	Tool     string `json:"tool,omitempty"`
}

type RunRestartRequest added in v0.1.16

type RunRestartRequest struct {
	FromFailed  bool    `json:"from_failed,omitempty"`
	GitLabToken *string `json:"gitlab_token,omitempty"`
}

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"`
}

Jump to

Keyboard shortcuts

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