stack

package
v0.1.0-rc.57 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: Apache-2.0 Imports: 38 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func PostgresServices

func PostgresServices(specs []factory.TargetSpec) []string

PostgresServices returns the postgres connection (= compose service) names among specs — the stores remotesnap can dump via docker-exec.

func ResolveRemoteSnap

func ResolveRemoteSnap(root string) (store remotesnap.Store, project string, ok bool, err error)

ResolveRemoteSnap builds the remote-side snapshot store for the project at root when it resolves to remote mode. ok=false ⇒ local mode (the caller uses the local snapstore). project is the registry name. Snapshots live under `<remote_path>/.snapshots/<project>` — a sibling of the rsync target, so `--delete` never touches them.

func SnapshotConns

func SnapshotConns(specs []factory.TargetSpec) (conns []snapstore.Conn, skipped []string, err error)

SnapshotConns turns resolved dev-diff-apply targets into the per-store snapstore.Conn list (a Snapshotter + on-disk file extension per connection) that snapstore.Save/Load drive. It is the bridge between the target DSNs and the branch-snapshot store — used by the branch-switch reconcile and (later) the manual `db snapshot` command. A connection whose dialect has no snapshot adapter is skipped (its name returned in `skipped`) rather than failing the whole snapshot.

func SyncStores

func SyncStores(root, console string, targets []factory.TargetSpec) error

SyncStores reconciles the given stores to the project's protos, through the console — the whole of `stack build --no-build`, with the targets supplied rather than resolved.

Exported for `w17ctl test`, whose stack publishes its stores on ports it allocates itself, so the addresses are known to the caller and to nobody else. The reconcile is otherwise identical: compile the protos, ask the console for the plan against what those databases HOLD, apply it.

⛔ Except for the BRANCH-switch reconcile, which is skipped here. These stores were created by the suite seconds ago and are destroyed when it finishes: there is no outgoing branch's data in them to snapshot, and no incoming branch's to restore. Running it anyway did both against the developer's LONG-LIVED stack — it snapshotted a store the suite had just created on behalf of whatever branch the last real build recorded, and when no snapshot for the current branch existed it "built fresh" through the repo's own compose, reaching for `w17-01-app-gateway:latest` from inside an ephemeral project. The snapshot guard caught the other half and said so:

snapstore Save catalog-postgres: the store holds N object(s) but its dump
carries none — the dump reached a DIFFERENT database than the one this
store names

which was true, and the reason is here rather than there.

Types

type BindCmd

type BindCmd struct {
	Mode string `` /* 166-byte string literal not displayed */
}

BindCmd is `w17ctl stack bind loopback|public` — choose the host interface docker publishes this project's ports on. Per-machine (devconfig), like the port map; NOT a codegen/lock input.

func (*BindCmd) Run

func (c *BindCmd) Run() error

type BuildCmd

type BuildCmd struct {
	Services []string `arg:"" optional:"" help:"Services to build; empty = the whole stack."`

	Protos          []string `` /* 235-byte string literal not displayed */
	Imports         []string `` /* 188-byte string literal not displayed */
	Targets         []string `` /* 218-byte string literal not displayed */
	Project         string   `name:"project" placeholder:"ID" help:"Project id. Empty = read from the current project's lock."`
	CompilerVersion string   `name:"compiler-version" placeholder:"VER" default:"dev" help:"Compiler version pinned into the advanced checkpoint."`
	By              string   `name:"by" placeholder:"ACTOR" help:"Actor stamp (checkpoint user_id). Empty = local OS user."`
	Console         string   `` /* 202-byte string literal not displayed */
	Reconcile       bool     `` /* 181-byte string literal not displayed */
	NoCodegen       bool     `` /* 190-byte string literal not displayed */
	Lossy           string   `` /* 194-byte string literal not displayed */
	NoSnapshot      bool     `` /* 326-byte string literal not displayed */
	CacheCap        string   `` /* 867-byte string literal not displayed */
	NoReclaim       bool     `` /* 358-byte string literal not displayed */
	NoBuild         bool     `` /* 327-byte string literal not displayed */
	// contains filtered or unexported fields
}

BuildCmd is `w17ctl stack build` — compile + build images, then **dev diff-apply** (docs/specs/storage/dev-db-lifecycle.md S5/S6): bring the developer's local stores up to the current branch proto by applying checkpoint→current directly, persisting no migration. No `up`.

The dev diff-apply step runs only when both `--proto` and `--target` are supplied (the local store DSNs to apply to) — otherwise build is image-only and prints a one-line skip note. Zero-flag auto-resolution of protos + local DSNs from the running stack is a documented follow-up; today the explicit flags mirror `migrate generate`.

func (*BuildCmd) ResolveTargets

func (c *BuildCmd) ResolveTargets(root string) ([]factory.TargetSpec, error)

ResolveTargets returns the dev-diff-apply targets: explicit --target wins; otherwise they are auto-resolved from the lock's connections + the dev-machine port allocation (the same ports `stack up` publishes). Skipped connections are reported so the dev sees why a store was left untouched.

func (*BuildCmd) Run

func (c *BuildCmd) Run() error

type CleanCmd

type CleanCmd struct {
	Console string `` /* 213-byte string literal not displayed */
}

CleanCmd — remove codegen output (pb stubs, FE clients, languages, the generated bits of each bundle) while preserving hand-written packages.

func (*CleanCmd) Run

func (c *CleanCmd) Run() error

type Cmd

type Cmd struct {
	Build   BuildCmd   `` /* 300-byte string literal not displayed */
	Up      UpCmd      `` /* 165-byte string literal not displayed */
	Down    DownCmd    `cmd:"" help:"Tear the local compose stack down: docker compose down -v (drops volumes unless --keep-volumes)."`
	Reset   ResetCmd   `` /* 258-byte string literal not displayed */
	Logs    LogsCmd    `cmd:"" help:"Follow service logs: docker compose logs -f."`
	Ps      PsCmd      `cmd:"" help:"List the stack's containers: docker compose ps."`
	Restart RestartCmd `cmd:"" help:"Restart the stack (or named services): docker compose restart."`

	// Remote-mode registry + selection (docs/experiments/remote-stack.md):
	// offload the whole stack to an SSH docker host, apps still on localhost.
	Remote  RemoteCmd   `` /* 129-byte string literal not displayed */
	Local   UseLocalCmd `cmd:"" help:"Pin THIS project back to local mode (the counterpart to 'stack remote use')."`
	SetMode SetModeCmd  `cmd:"" name:"set-mode" help:"Set the GLOBAL default stack mode (local | remote) for projects that don't pin one."`
	Bind    BindCmd     `` /* 173-byte string literal not displayed */
}

Cmd is the `w17ctl stack` parent — the local docker-compose lifecycle verbs (up / down / logs / ps / restart). `clean` stays top-level: it removes codegen output, not the compose stack.

type DownCmd

type DownCmd struct {
	KeepVolumes bool `name:"keep-volumes" help:"Keep volume data (omit -v). Default drops volumes — ALL local DB data is lost."`
	// contains filtered or unexported fields
}

DownCmd — tear the local stack down. Drops volumes by default (matches the former manage.sh `down -v`); --keep-volumes preserves data.

func (*DownCmd) Run

func (c *DownCmd) Run() error

type LogsCmd

type LogsCmd struct {
	Services []string `arg:"" optional:"" help:"Services to tail; empty = all."`
	NoFollow bool     `name:"no-follow" help:"Print current logs and exit instead of following."`
	// contains filtered or unexported fields
}

LogsCmd — follow service logs.

func (*LogsCmd) Run

func (c *LogsCmd) Run() error

type PsCmd

type PsCmd struct {
	// contains filtered or unexported fields
}

PsCmd — list the stack's containers.

func (*PsCmd) Run

func (c *PsCmd) Run() error

type RemoteAddCmd

type RemoteAddCmd struct {
	Name string `arg:"" help:"Name for this remote (a Remotes key you reference with --remote / 'stack remote use')."`
	SSH  string `name:"ssh" required:"" placeholder:"user@host[:port]" help:"SSH destination for ssh/rsync. An ssh_config alias is fine."`
	Path string `name:"path" required:"" placeholder:"/srv/w17" help:"Base dir on the server; each project gets a <path>/<project> subdir."`
}

RemoteAddCmd — register (or overwrite) a named remote docker host.

func (*RemoteAddCmd) Run

func (c *RemoteAddCmd) Run() error

type RemoteCmd

type RemoteCmd struct {
	Add    RemoteAddCmd    `cmd:"" help:"Register a remote docker host (global): --ssh user@host --path /srv/w17."`
	List   RemoteListCmd   `cmd:"" help:"List registered remote docker hosts."`
	Remove RemoteRemoveCmd `cmd:"" help:"Unregister a remote docker host (clears it from the default + any project pins)."`
	Use    UseRemoteCmd    `cmd:"" help:"Pin THIS project to remote mode on a named remote host."`
}

RemoteCmd is `stack remote` — manage the registry of remote docker hosts AND pin THIS project to one (`remote use <name>`). The local counterpart is the top-level `stack local`.

type RemoteListCmd

type RemoteListCmd struct{}

RemoteListCmd — list registered remotes, marking the default.

func (*RemoteListCmd) Run

func (c *RemoteListCmd) Run() error

type RemoteRemoveCmd

type RemoteRemoveCmd struct {
	Name string `arg:"" help:"Remote name to unregister."`
}

RemoteRemoveCmd — unregister a remote (cascades to default + pins).

func (*RemoteRemoveCmd) Run

func (c *RemoteRemoveCmd) Run() error

type ResetCmd

type ResetCmd struct {
	Protos          []string `` /* 217-byte string literal not displayed */
	Imports         []string `` /* 188-byte string literal not displayed */
	Project         string   `name:"project" placeholder:"ID" help:"Project id. Empty = read from the lock."`
	Console         string   `` /* 187-byte string literal not displayed */
	By              string   `name:"by" placeholder:"ACTOR" help:"Actor stamp (checkpoint user_id). Empty = local OS user."`
	CompilerVersion string   `name:"compiler-version" placeholder:"VER" default:"dev" help:"Compiler version pinned into the adopted checkpoint."`
	KeepData        bool     `` /* 185-byte string literal not displayed */
}

ResetCmd is `w17ctl stack reset` — the one recovery from a tangled local dev DB state (a wiped volume, a checkpoint out of sync with the store, the first-build db/init collision). It reconciles the two halves of the dev DB lifecycle so the next `stack build` is a clean no-op:

  1. wipe the local stores — docker compose down -v (drops all volumes);
  2. bring the stack up — a fresh volume re-applies db/init's full current schema via docker-entrypoint-initdb.d;
  3. adopt the checkpoint — record the CURRENT schema as the initiative's checkpoint WITHOUT applying any DDL. Safe precisely because step 2 just re-created that schema from db/init, so the live store already equals current — re-applying would collide, adopting cannot.

This is the deliberate escape hatch: any local DB tangle is always recoverable through w17ctl, never a hand-run psql. It assumes the generated db/init is current (run `w17ctl codegen` first if the protos changed) — it adopts the current protos as the baseline. Fixture seed data (e.g. a turnkey acl_roles admin role) is a separate step: `w17ctl fixtures apply`.

func (*ResetCmd) Run

func (c *ResetCmd) Run() error

type RestartCmd

type RestartCmd struct {
	Services []string `arg:"" optional:"" help:"Services to restart; empty = all."`
	// contains filtered or unexported fields
}

RestartCmd — restart the stack (or named services).

func (*RestartCmd) Run

func (c *RestartCmd) Run() error

type SetModeCmd

type SetModeCmd struct {
	Mode   string `arg:"" enum:"local,remote" help:"Default mode for projects that don't pin one: local | remote."`
	Remote string `name:"remote" placeholder:"NAME" help:"When mode=remote, also set the default remote to this registered name."`
}

SetModeCmd — set the GLOBAL default execution mode.

func (*SetModeCmd) Run

func (c *SetModeCmd) Run() error

type UpCmd

type UpCmd struct {
	NoSync  bool   `name:"no-sync" help:"Start the containers without syncing the stores' schema from the console."`
	Console string `` /* 129-byte string literal not displayed */

	Services  []string `` /* 129-byte string literal not displayed */
	Preset    string   `name:"preset" short:"p" help:"Run preset to apply (services + extra env). Empty = the project's active preset, if any."`
	Build     bool     `` /* 180-byte string literal not displayed */
	NoReclaim bool     `` /* 172-byte string literal not displayed */
	CacheCap  string   `` /* 192-byte string literal not displayed */
	// contains filtered or unexported fields
}

UpCmd — bring the local stack (or named services) up.

Unlike a raw `docker compose up`, this drives through the dev-machine-local project registry (devconfig): it auto-registers the project, allocates it unique host ports across ALL installed projects, and injects those ports (plus an optional preset's extra env) into the compose subprocess. So two projects never collide on an exposed port without any .env juggling. A preset (`--preset`, or the project's active preset) also selects which services to start — handy to run just the admin binary on a weak machine.

func (*UpCmd) Run

func (c *UpCmd) Run() error

type UseLocalCmd

type UseLocalCmd struct{}

UseLocalCmd — pin THIS project back to local mode.

func (*UseLocalCmd) Run

func (c *UseLocalCmd) Run() error

type UseRemoteCmd

type UseRemoteCmd struct {
	Name string `arg:"" help:"Registered remote to pin this project to."`
}

UseRemoteCmd — pin THIS project to remote mode + a specific remote.

func (*UseRemoteCmd) Run

func (c *UseRemoteCmd) Run() error

Jump to

Keyboard shortcuts

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