Documentation
¶
Index ¶
- func CardinalBuildImageNames(services []service.Service) []string
- func IsCardinalService(s service.Service) bool
- func NewClientConfig(projectDir string, debug bool) (*service.Config, error)
- func WithClient(projectDir string, debug bool, opts *ClientOptions, ...) error
- type Client
- func (c *Client) BuildCardinalImages(ctx context.Context, services []service.Service, progress func(Progress)) error
- func (c *Client) CardinalDebugHostPort(ctx context.Context, containerName string) (int, error)
- func (c *Client) Close() error
- func (c *Client) GetContainerLogs(ctx context.Context, containerName string, tailLines int, sinceSeconds int) (string, error)
- func (c *Client) ImagesToPull(ctx context.Context, services []service.Service) []string
- func (c *Client) InspectContainer(ctx context.Context, containerName string) (container.InspectResponse, error)
- func (c *Client) ListCardinalContainersByNamespace(ctx context.Context, namespace string, all bool) ([]string, error)
- func (c *Client) PruneCardinalImages(ctx context.Context) error
- func (c *Client) PullImageRefs(ctx context.Context, refs []string, progress func(Progress)) error
- func (c *Client) PullImages(ctx context.Context, services []service.Service, progress func(Progress)) error
- func (c *Client) RefsToPull(ctx context.Context, refs []string) []string
- func (c *Client) ResolveServices(builders ...service.Builder) []service.Service
- type ClientOptions
- type Progress
- type State
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CardinalBuildImageNames ¶
CardinalBuildImageNames returns the unique Cardinal image tags that would be built for services, preserving first-seen service order.
func IsCardinalService ¶
IsCardinalService returns true if the given service represents a Cardinal shard (identified by the Cardinal namespace label).
func NewClientConfig ¶
NewClientConfig builds a service.Config by reading world.toml from projectDir. projectDir must be an absolute path to the World Engine project root.
func WithClient ¶
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
func (*Client) BuildCardinalImages ¶
func (c *Client) BuildCardinalImages( ctx context.Context, services []service.Service, progress func(Progress), ) error
BuildCardinalImages builds Docker images for all Cardinal shard services using the dockerd-embedded BuildKit. Non-Cardinal services in the slice are silently skipped. The optional progress callback is called as each image build progresses. Passing nil means "no progress needed". The callback is serialized internally — callers do not need to synchronize.
Progress fields used:
- Name: the image reference being built (e.g. "my-shard:latest")
- State: StateBuilding while in progress, StateBuilt on completion
- Err: non-nil when the individual image build fails (the function's return value is the authoritative error; Err is for per-item UI updates)
func (*Client) CardinalDebugHostPort ¶
CardinalDebugHostPort returns the host port bound to the Cardinal debug port (8080/tcp) for the given container. Use this to connect to the debug API from the host without relying on index-based port formulas. Returns an error if the container is not found or the port binding is missing.
func (*Client) GetContainerLogs ¶
func (c *Client) GetContainerLogs( ctx context.Context, containerName string, tailLines int, sinceSeconds int, ) (string, error)
GetContainerLogs returns logs for the given container. It supports optional tail and sinceSeconds filters so callers can limit the volume of logs returned. If both tailLines and sinceSeconds are specified, logs are filtered by time first, then limited to the specified number of tail lines.
func (*Client) ImagesToPull ¶
ImagesToPull is PullImages' dry run: returns the image names it would actually pull for services (cached/non-":latest" images excluded), without pulling. Empty means callers can skip opening progress UI.
func (*Client) InspectContainer ¶
func (c *Client) InspectContainer(ctx context.Context, containerName string) (container.InspectResponse, error)
InspectContainer inspects a Docker container by name and returns its inspection data.
func (*Client) ListCardinalContainersByNamespace ¶
func (c *Client) ListCardinalContainersByNamespace(ctx context.Context, namespace string, all bool) ([]string, error)
ListCardinalContainersByNamespace returns the names of Cardinal containers for a given namespace.
func (*Client) PruneCardinalImages ¶
PruneCardinalImages removes Docker images that were built by world-cli for Cardinal (identified via the world-cli=cardinal image label), as well as old NATS images used by world start. This is intended to be called after containers have been purged.
func (*Client) PullImageRefs ¶
PullImageRefs pulls each of refs (bare image refs, e.g. "docker.io/rancher/k3s:v1.31.5-k3s1") concurrently, deduping and skipping cached images (same ":latest" policy as PullImages). The plain-ref counterpart to PullImages for callers with an explicit image list, like cluster.Client.RequiredBootstrapImages. Progress fields match PullImages'.
func (*Client) PullImages ¶
func (c *Client) PullImages(ctx context.Context, services []service.Service, progress func(Progress)) error
PullImages pulls all required images for the given services concurrently. The optional progress callback is called as each image pull progresses. Passing nil means "no progress needed". The callback is serialized internally — callers do not need to synchronize.
Progress fields used:
- Name: the image reference being pulled (e.g. "docker.io/library/golang:1.25")
- State: StatePulling while in progress, StatePulled on completion
- Current: download percentage (0–100), only meaningful when State == StatePulling
- Total: always 100
- Err: non-nil when the individual image pull fails (the function's return value is the authoritative error; Err is for per-item UI updates)
func (*Client) RefsToPull ¶
RefsToPull is PullImageRefs' dry run: returns the refs it would actually pull (deduplicated), without pulling. Empty means callers can skip opening progress UI.
type ClientOptions ¶
ClientOptions holds optional configuration for a Client. Pass nil to NewClient for default behaviour (silent logging).
type Progress ¶
type Progress struct {
Name string // resource identifier: container name, image name, etc.
State State // current phase of the operation
Current int64 // 0–100 percent, only meaningful when State == StatePulling
Total int64 // 100, only meaningful when State == StatePulling
Err error // non-nil on failure
}
Progress reports the state of a long-running operation.
type State ¶
type State string
State is a machine-readable phase of a long-running docker operation.
const ( StatePulling State = "pulling" StatePulled State = "pulled" StateBuilding State = "building" StateBuilt State = "built" StateStarting State = "starting" // running but not yet ready; cardinal-editor shows this for unready shards StateStarted State = "started" StateStopped State = "stopped" )
Progress states.
Source Files
Directories