takoapi

package
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Jul 18, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package takoapi defines Tako's canonical schema and identity value types.

The package is intentionally small and transport-neutral. It is a foundation for API contracts, replicated state documents, local caches, and future SDKs; it is not a takod transport client and must not depend on CLI, SSH, Docker, cobra/viper, or internal packages.

Identity fields deliberately separate source identity, whole-deployment revision identity, per-service revision identity, image identity, and optional git display metadata. Git metadata is trace information only and should not be used as a synthetic deployment revision for non-git sources.

Index

Constants

View Source 
const (
	// APIVersionV1Alpha1 is the first additive canonical schema version.
	APIVersionV1Alpha1 = "tako.redentor.dev/v1alpha1"

	// APIVersionCurrent points at the current canonical schema version for new documents.
	APIVersionCurrent = APIVersionV1Alpha1

	// KindDeploymentDocument identifies a canonical desired deployment document.
	KindDeploymentDocument = "Deployment"

	// KindDeploymentService identifies a service entry within a deployment document.
	KindDeploymentService = "DeploymentService"
)
View Source 
const (
	// StateSchemaVersionCurrent is the current takod /v1/state document schema version.
	StateSchemaVersionCurrent = 1

	// StateDocumentDesired is the takod /v1/state document name for desired state.
	StateDocumentDesired = "desired"
	// StateDocumentActual is the takod /v1/state document name for aggregate actual state.
	StateDocumentActual = "actual"
	// StateDocumentActualNode is the takod /v1/state document name for per-node actual state.
	StateDocumentActualNode = "actual-node"
	// StateDocumentEvent is the takod /v1/state document name for append-only events.
	StateDocumentEvent = "event"
	// StateDocumentHistory is the takod /v1/state document name for deployment history.
	StateDocumentHistory = "history"
	// StateDocumentDeployment is the takod /v1/state document name for a deployment record.
	StateDocumentDeployment = "deployment"

	// KindDesiredStateDocument identifies a canonical desired state document.
	KindDesiredStateDocument = "DesiredState"
	// KindDesiredServiceDocument identifies a service entry in desired state.
	KindDesiredServiceDocument = "DesiredService"
	// KindActualStateDocument identifies a canonical aggregate actual state document.
	KindActualStateDocument = "ActualState"
	// KindActualNodeStateDocument identifies a canonical per-node actual state document.
	KindActualNodeStateDocument = "ActualNodeState"
	// KindActualServiceDocument identifies a service entry in actual state.
	KindActualServiceDocument = "ActualService"
	// KindStateEventDocument identifies a canonical state event document.
	KindStateEventDocument = "StateEvent"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ActualNodeStateDocument 

type ActualNodeStateDocument struct {
	APIVersion    string                           `json:"apiVersion"`
	Kind          string                           `json:"kind"`
	SchemaVersion int                              `json:"schemaVersion"`
	Project       string                           `json:"project"`
	Environment   string                           `json:"environment"`
	Node          string                           `json:"node"`
	Services      map[string]ActualServiceDocument `json:"services"`
	CapturedAt    time.Time                        `json:"capturedAt"`
}

ActualNodeStateDocument is Tako's canonical per-node runtime state schema for takod /v1/state actual-node documents. Node remains top-level for takod identity validation.

func NewActualNodeStateDocument 

func NewActualNodeStateDocument(project, environment, node string) ActualNodeStateDocument

NewActualNodeStateDocument returns a per-node actual state document initialized for the current canonical API and state schema versions.

type ActualServiceDocument 

type ActualServiceDocument struct {
	APIVersion        string            `json:"apiVersion,omitempty"`
	Kind              string            `json:"kind,omitempty"`
	Name              string            `json:"name"`
	Image             string            `json:"image,omitempty"`
	RevisionImages    map[string]string `json:"revisionImages,omitempty"`
	Replicas          int               `json:"replicas"`
	Containers        []string          `json:"containers,omitempty"`
	ConfigHash        string            `json:"configHash,omitempty"`
	RuntimeID         string            `json:"runtimeId,omitempty"`
	Persistent        bool              `json:"persistent,omitempty"`
	CurrentRevision   string            `json:"currentRevision,omitempty"`
	PreviousRevision  string            `json:"previousRevision,omitempty"`
	WarmingRevisions  []string          `json:"warmingRevisions,omitempty"`
	DeployStrategy    string            `json:"deployStrategy,omitempty"`
	ActiveContainers  []string          `json:"activeContainers,omitempty"`
	WarmingContainers []string          `json:"warmingContainers,omitempty"`
}

ActualServiceDocument is a JSON-friendly runtime service state schema.

type ActualStateDocument 

type ActualStateDocument struct {
	APIVersion    string                             `json:"apiVersion"`
	Kind          string                             `json:"kind"`
	SchemaVersion int                                `json:"schemaVersion"`
	Project       string                             `json:"project"`
	Environment   string                             `json:"environment"`
	Node          string                             `json:"node,omitempty"`
	TargetNodes   []string                           `json:"targetNodes,omitempty"`
	Services      map[string]ActualServiceDocument   `json:"services"`
	Nodes         map[string]ActualNodeStateDocument `json:"nodes,omitempty"`
	CapturedAt    time.Time                          `json:"capturedAt"`
}

ActualStateDocument is Tako's canonical aggregate runtime state schema for takod /v1/state. Project and Environment remain top-level for takod identity validation.

func NewActualStateDocument 

func NewActualStateDocument(project, environment string) ActualStateDocument

NewActualStateDocument returns an aggregate actual state document initialized for the current canonical API and state schema versions.

type DeploymentDocument 

type DeploymentDocument struct {
	APIVersion  string                       `json:"apiVersion"`
	Kind        string                       `json:"kind"`
	Project     string                       `json:"project"`
	Environment string                       `json:"environment,omitempty"`
	Revision    RevisionIdentity             `json:"revision"`
	Source      SourceIdentity               `json:"source,omitempty"`
	Git         *GitMetadata                 `json:"git,omitempty"`
	Services    map[string]DeploymentService `json:"services,omitempty"`
	CreatedAt   time.Time                    `json:"createdAt,omitempty"`
}

DeploymentDocument is the minimal canonical desired deployment document shape.

func NewDeploymentDocument 

func NewDeploymentDocument(project, environment string) DeploymentDocument

NewDeploymentDocument returns a deployment document initialized with the current version and kind constants.

type DeploymentHistoryDocument 

type DeploymentHistoryDocument struct {
	ProjectName string                     `json:"projectName"`
	Environment string                     `json:"environment,omitempty"`
	Server      string                     `json:"server"`
	Deployments []*DeploymentStateDocument `json:"deployments"`
	LastUpdated time.Time                  `json:"lastUpdated"`
}

DeploymentHistoryDocument contains all historical deployments for a project environment. Its JSON shape intentionally matches internal/state.DeploymentHistory.

type DeploymentService 

type DeploymentService struct {
	Kind     string                  `json:"kind,omitempty"`
	Name     string                  `json:"name"`
	Revision ServiceRevisionIdentity `json:"revision,omitempty"`
	Image    ImageIdentity           `json:"image,omitempty"`
	Source   SourceIdentity          `json:"source,omitempty"`
}

DeploymentService is a canonical service entry within a DeploymentDocument.

type DeploymentStateDocument 

type DeploymentStateDocument struct {
	ID             string                          `json:"id"`
	Timestamp      time.Time                       `json:"timestamp"`
	ProjectName    string                          `json:"projectName"`
	Environment    string                          `json:"environment,omitempty"`
	Version        string                          `json:"version"`
	Status         DeploymentStatus                `json:"status"`
	Services       map[string]ServiceStateDocument `json:"services"`
	User           string                          `json:"user"`
	Host           string                          `json:"host"`
	Duration       time.Duration                   `json:"duration"`
	Message        string                          `json:"message"`
	Error          string                          `json:"error,omitempty"`
	GitCommit      string                          `json:"gitCommit,omitempty"`
	GitCommitShort string                          `json:"gitCommitShort,omitempty"`
	GitBranch      string                          `json:"gitBranch,omitempty"`
	GitCommitMsg   string                          `json:"gitCommitMsg,omitempty"`
	GitAuthor      string                          `json:"gitAuthor,omitempty"`
	CLIVersion     string                          `json:"cliVersion,omitempty"`
	CLICommit      string                          `json:"cliCommit,omitempty"`
}

DeploymentStateDocument represents one historical deployment record. Its JSON shape intentionally matches internal/state.DeploymentState so existing replicated deployment documents can be decoded into this public schema.

type DeploymentStatus 

type DeploymentStatus string

DeploymentStatus represents a deployment outcome. 

const (
	// StatusInProgress means a deployment is still running.
	StatusInProgress DeploymentStatus = "in_progress"
	// StatusSuccess means a deployment completed successfully.
	StatusSuccess DeploymentStatus = "success"
	// StatusWarmed means a deployment warmed a new revision without switching all traffic.
	StatusWarmed DeploymentStatus = "warmed"
	// StatusFailed means a deployment failed.
	StatusFailed DeploymentStatus = "failed"
	// StatusRolledBack means a deployment was rolled back.
	StatusRolledBack DeploymentStatus = "rolled_back"
)

type DesiredBuildDocument added in v0.9.0 

type DesiredBuildDocument struct {
	Context    string   `json:"context"`
	ArgKeys    []string `json:"argKeys,omitempty"`
	Target     string   `json:"target,omitempty"`
	Dockerfile string   `json:"dockerfile,omitempty"`
}

type DesiredServiceDocument 

type DesiredServiceDocument struct {
	APIVersion      string                      `json:"apiVersion,omitempty"`
	Kind            string                      `json:"kind,omitempty"`
	WorkloadKind    string                      `json:"workloadKind,omitempty"`
	Name            string                      `json:"name"`
	Type            string                      `json:"type,omitempty"`
	Image           string                      `json:"image,omitempty"`
	ImageFrom       string                      `json:"imageFrom,omitempty"`
	Build           string                      `json:"build,omitempty"`
	BuildArgKeys    []string                    `json:"buildArgKeys,omitempty"`
	BuildTarget     string                      `json:"buildTarget,omitempty"`
	Command         string                      `json:"command,omitempty"`
	CommandArgs     []string                    `json:"commandArgs,omitempty"`
	Entrypoint      string                      `json:"entrypoint,omitempty"`
	EntrypointArgs  []string                    `json:"entrypointArgs,omitempty"`
	Labels          map[string]string           `json:"labels,omitempty"`
	Port            int                         `json:"port,omitempty"`
	Replicas        int                         `json:"replicas"`
	Assignments     []ReplicaAssignmentDocument `json:"assignments,omitempty"`
	Restart         string                      `json:"restart,omitempty"`
	Persistent      bool                        `json:"persistent,omitempty"`
	Placement       json.RawMessage             `json:"placement,omitempty"`
	Domains         []string                    `json:"domains,omitempty"`
	Volumes         []string                    `json:"volumes,omitempty"`
	Files           []ServiceFileDocument       `json:"files,omitempty"`
	EnvKeys         []string                    `json:"envKeys,omitempty"`
	EnvFile         bool                        `json:"envFile,omitempty"`
	User            string                      `json:"user,omitempty"`
	WorkingDir      string                      `json:"workingDir,omitempty"`
	StopGracePeriod string                      `json:"stopGracePeriod,omitempty"`
	Init            bool                        `json:"init,omitempty"`
	ExtraHosts      []string                    `json:"extraHosts,omitempty"`
	Ulimits         map[string]UlimitDocument   `json:"ulimits,omitempty"`
	ShmSize         string                      `json:"shmSize,omitempty"`
	SecretRefs      []string                    `json:"secretRefs,omitempty"`
	DependsOn       []string                    `json:"dependsOn,omitempty"`
	HealthCheck     json.RawMessage             `json:"healthCheck,omitempty"`
	DeployStrategy  string                      `json:"deployStrategy,omitempty"`
	RemovalPending  bool                        `json:"removalPending,omitempty"`
}

DesiredServiceDocument is a JSON-friendly desired service schema. Config-like nested fields that belong to deployment configuration, not state identity, are represented without importing pkg/config.

type DesiredStateDocument 

type DesiredStateDocument struct {
	APIVersion    string                            `json:"apiVersion"`
	Kind          string                            `json:"kind"`
	SchemaVersion int                               `json:"schemaVersion"`
	RevisionID    string                            `json:"revisionId"`
	Project       string                            `json:"project"`
	Environment   string                            `json:"environment"`
	Source        string                            `json:"source"`
	TargetNodes   []string                          `json:"targetNodes"`
	Builds        map[string]DesiredBuildDocument   `json:"builds,omitempty"`
	Services      map[string]DesiredServiceDocument `json:"services"`
	Git           *GitMetadata                      `json:"git,omitempty"`
	CreatedAt     time.Time                         `json:"createdAt"`
}

DesiredStateDocument is Tako's canonical desired state schema for takod /v1/state. Project, Environment, and RevisionID remain top-level so existing takod state validation can accept the document without transport coupling.

func NewDesiredStateDocument 

func NewDesiredStateDocument(project, environment, revisionID string) DesiredStateDocument

NewDesiredStateDocument returns a desired state document initialized for the current canonical API and state schema versions.

type GitMetadata 

type GitMetadata struct {
	Commit      string `json:"commit,omitempty"`
	CommitShort string `json:"commitShort,omitempty"`
	Branch      string `json:"branch,omitempty"`
	Message     string `json:"message,omitempty"`
	Author      string `json:"author,omitempty"`
}

GitMetadata is optional display and trace metadata for git-backed sources. It is not a deployment revision identity and may be omitted for directory, archive, image, CI, or other non-git deployments.

func (GitMetadata) HasCommit 

func (g GitMetadata) HasCommit() bool

HasCommit reports whether git commit metadata is present. It intentionally does not imply that the deployment revision ID is a git commit.

func (GitMetadata) IsZero 

func (g GitMetadata) IsZero() bool

func (GitMetadata) Normalize 

func (g GitMetadata) Normalize() GitMetadata

type HealthCheckStateDocument 

type HealthCheckStateDocument struct {
	Enabled   bool      `json:"enabled"`
	Path      string    `json:"path"`
	Healthy   bool      `json:"healthy"`
	LastCheck time.Time `json:"lastCheck"`
}

HealthCheckStateDocument represents health check status in deployment history.

type ImageIdentity 

type ImageIdentity struct {
	Ref    string `json:"ref,omitempty"`
	ID     string `json:"id,omitempty"`
	Digest string `json:"digest,omitempty"`
}

ImageIdentity identifies a runtime artifact independently from the source and deployment revision that selected it.

func (ImageIdentity) IsValid 

func (i ImageIdentity) IsValid() bool

func (ImageIdentity) IsZero 

func (i ImageIdentity) IsZero() bool

func (ImageIdentity) Normalize 

func (i ImageIdentity) Normalize() ImageIdentity

type ReplicaAssignmentDocument added in v0.10.0 

type ReplicaAssignmentDocument struct {
	Slot   int    `json:"slot"`
	NodeID string `json:"nodeId"`
	Node   string `json:"node"`
}

ReplicaAssignmentDocument is the persisted sticky replica-to-node binding.

type RevisionIdentity 

type RevisionIdentity struct {
	ID           string `json:"id,omitempty"`
	SourceDigest string `json:"sourceDigest,omitempty"`
	ConfigDigest string `json:"configDigest,omitempty"`
}

RevisionIdentity identifies a whole deployment revision accepted by Tako. It must be independent from optional git metadata.

func (RevisionIdentity) IsValid 

func (r RevisionIdentity) IsValid() bool

func (RevisionIdentity) IsZero 

func (r RevisionIdentity) IsZero() bool

func (RevisionIdentity) Normalize 

func (r RevisionIdentity) Normalize() RevisionIdentity

type RunStateDocument added in v0.9.0 

type RunStateDocument struct {
	Command    []string `json:"command"`
	Server     string   `json:"server"`
	Image      string   `json:"image"`
	ExitCode   int      `json:"exitCode"`
	DurationMs int64    `json:"durationMs"`
}

type ServiceFileDocument added in v0.9.0 

type ServiceFileDocument struct {
	Source string `json:"source"`
	Target string `json:"target"`
	Secret bool   `json:"secret,omitempty"`
	Owner  string `json:"owner,omitempty"`
}

type ServiceFileStateDocument added in v0.9.0 

type ServiceFileStateDocument struct {
	Target string `json:"target"`
	Secret bool   `json:"secret,omitempty"`
	Owner  string `json:"owner,omitempty"`
}

type ServiceRevisionIdentity 

type ServiceRevisionIdentity struct {
	ID           string `json:"id,omitempty"`
	Service      string `json:"service,omitempty"`
	ConfigDigest string `json:"configDigest,omitempty"`
}

ServiceRevisionIdentity identifies a per-service/container revision. It is distinct from RevisionIdentity, which identifies the whole deployment.

func (ServiceRevisionIdentity) IsValid 

func (r ServiceRevisionIdentity) IsValid() bool

func (ServiceRevisionIdentity) IsZero 

func (r ServiceRevisionIdentity) IsZero() bool

func (ServiceRevisionIdentity) Normalize 

func (r ServiceRevisionIdentity) Normalize() ServiceRevisionIdentity

type ServiceStateDocument 

type ServiceStateDocument struct {
	Kind             string                     `json:"kind,omitempty"`
	Name             string                     `json:"name"`
	Image            string                     `json:"image"`
	ConfigHash       string                     `json:"configHash,omitempty"`
	SharedBuild      string                     `json:"sharedBuild,omitempty"`
	SharedBuildHash  string                     `json:"sharedBuildHash,omitempty"`
	FilesContentHash string                     `json:"filesContentHash,omitempty"`
	Files            []ServiceFileStateDocument `json:"files,omitempty"`
	Run              *RunStateDocument          `json:"run,omitempty"`
	ImageID          string                     `json:"imageId"`
	ContainerID      string                     `json:"containerId"`
	Port             int                        `json:"port"`
	Replicas         int                        `json:"replicas"`
	Env              map[string]string          `json:"env"`
	HealthCheck      HealthCheckStateDocument   `json:"healthCheck"`
}

ServiceStateDocument represents one service in a deployment history record.

type SourceIdentity 

type SourceIdentity struct {
	Kind   SourceKind `json:"kind,omitempty"`
	Ref    string     `json:"ref,omitempty"`
	Digest string     `json:"digest,omitempty"`
}

SourceIdentity identifies the deployment input independently from git metadata and independently from the durable deployment revision ID.

func (SourceIdentity) IsValid 

func (s SourceIdentity) IsValid() bool

IsValid reports whether the source identity is structurally usable.

func (SourceIdentity) IsZero 

func (s SourceIdentity) IsZero() bool

IsZero reports whether no source identity was supplied.

func (SourceIdentity) Normalize 

func (s SourceIdentity) Normalize() SourceIdentity

Normalize returns a copy with surrounding whitespace removed from string fields.

type SourceKind 

type SourceKind string

SourceKind describes the operator input that produced a deployment revision. 

const (
	SourceKindGit       SourceKind = "git"
	SourceKindDirectory SourceKind = "directory"
	SourceKindArchive   SourceKind = "archive"
	SourceKindImage     SourceKind = "image"
)

func (SourceKind) IsValid 

func (k SourceKind) IsValid() bool

IsValid reports whether k is one of Tako's canonical source kinds.

type StateEventDocument 

type StateEventDocument struct {
	APIVersion    string            `json:"apiVersion"`
	Kind          string            `json:"kind"`
	SchemaVersion int               `json:"schemaVersion"`
	Type          string            `json:"type"`
	Project       string            `json:"project"`
	Environment   string            `json:"environment"`
	RevisionID    string            `json:"revisionId,omitempty"`
	Service       string            `json:"service,omitempty"`
	Message       string            `json:"message,omitempty"`
	Details       map[string]string `json:"details,omitempty"`
	Time          time.Time         `json:"time"`
}

StateEventDocument is Tako's canonical append-only event schema for takod /v1/state. Project and Environment remain top-level for takod identity validation.

func NewStateEventDocument 

func NewStateEventDocument(project, environment, eventType string) StateEventDocument

NewStateEventDocument returns an event document initialized for the current canonical API and state schema versions.

type UlimitDocument added in v0.9.0 

type UlimitDocument struct {
	Soft int64 `json:"soft"`
	Hard int64 `json:"hard"`
}

Source Files

View all Source files

Directories

Path Synopsis
Package events defines Tako's canonical engine event schema.
 Package events defines Tako's canonical engine event schema.
Package ptystream defines the framed duplex byte-stream protocol spoken over a hijacked takod exec connection.
 Package ptystream defines the framed duplex byte-stream protocol spoken over a hijacked takod exec connection.
Package stateclient provides a small typed client for takod /v1/state over the existing private takodclient transport.
 Package stateclient provides a small typed client for takod /v1/state over the existing private takodclient transport.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.