runtime

Documentation

Overview

Package runtime encapsulates the unified IPC bootstrap sequence that every Pando entrypoint must follow: derive ports, try the lock, open RW or RO DB, and wire services accordingly.

Index

• type BootstrapResult
  • func Bootstrap(ctx context.Context, workdir, instanceID string) (*BootstrapResult, error)
• type Role

Types

type BootstrapResult

type BootstrapResult struct {
	Role Role

	// Querier is the db.Querier callers should use for all DB operations.
	// Primary: direct db.New(SQLDB). Secondary: a DBProxy that forwards writes
	// to the primary via ZMQ RPC and serves reads from the local RO connection.
	Querier db.Querier

	// SQLDB is the underlying *sql.DB. Primary holds a RW connection with WAL
	// pragmas applied and migrations run. Secondary holds a RO connection.
	SQLDB *sql.DB

	// Bus is non-nil only on the primary instance.
	Bus *ipc.Bus

	// IPCClient is non-nil only on the secondary instance.
	IPCClient *ipc.Client

	InstanceID string
	PubPort    int
	RPCPort    int

	// LockFile is the open flock file held by the primary, nil on secondary.
	LockFile *os.File

	// Watcher monitors primary liveness. Always non-nil; disabled by default (feature flag).
	// Callers can call Watcher.SetEnabled(true) to opt in to automatic failover.
	Watcher *failover.Watcher

	// Cleanup releases all resources acquired during Bootstrap in reverse order.
	// The caller MUST call this exactly once on shutdown.
	Cleanup func()
}

BootstrapResult carries everything a caller needs after Bootstrap returns. Call Cleanup() on shutdown to release resources in correct order.

func Bootstrap

func Bootstrap(ctx context.Context, workdir, instanceID string) (*BootstrapResult, error)

Bootstrap runs the unified startup sequence for the given workdir.

1. Derive deterministic PUB/RPC ports from the path.
2. Attempt to acquire the exclusive IPC lock.
3. Primary: open RW DB (with migrations), create Bus, create direct Querier.
4. Secondary: open RO DB, create IPC Client, create DBProxy Querier.

On lock error the function continues as primary so the caller does not lose functionality — consistent with the existing root.go behaviour.

type Role

type Role string

Role describes the IPC role that this instance took during bootstrap.

const (
	RolePrimary   Role = "primary"
	RoleSecondary Role = "secondary"
)