onboarding

Documentation

Overview

Package onboarding holds helpers used by `tars init` (and its alias `tars onboard`) to bring a fresh install all the way from "no config" to a running server with the setup wizard open in a browser.

Index

• Constants
• func FormatLoopbackAddr(port int) string
• func ParseAPIAddrPort(addr string) (int, error)
• func PickFreePort(candidates []int) (int, error)
• func PortRange(start, end int) []int
• func WaitForHealthz(ctx context.Context, baseURL string, interval time.Duration) error
• type SpawnOptions
• type SpawnResult
  • func SpawnDetached(opts SpawnOptions) (SpawnResult, error)

Constants

const DefaultPortRangeEnd = 43199

DefaultPortRangeEnd bounds the auto-pick scan. 20 ports is enough for a developer machine that already runs a few local servers; beyond that the user should pass --port explicitly.

const DefaultPortRangeStart = 43180

DefaultPortRangeStart is the first port the onboarding picker tries when the user has not pinned an address. It matches tarsserver.DefaultAPIAddr so existing service plists keep working.

Functions

func FormatLoopbackAddr

func FormatLoopbackAddr(port int) string

FormatLoopbackAddr returns the canonical "127.0.0.1:<port>" string the rest of TARS uses for the API listener.

func ParseAPIAddrPort

func ParseAPIAddrPort(addr string) (int, error)

ParseAPIAddrPort extracts the port number from a host:port string. The host portion is ignored. Returns an error if the address is malformed or the port is not a valid integer.

func PickFreePort

func PickFreePort(candidates []int) (int, error)

PickFreePort returns the first candidate that can be bound on the loopback interface. A candidate of 0 asks the kernel to assign any free port (useful in tests). The returned port is the actual port, not the candidate value. Returns an error if every candidate is busy.

func PortRange

func PortRange(start, end int) []int

PortRange returns an inclusive list of ports between start and end.

func WaitForHealthz

func WaitForHealthz(ctx context.Context, baseURL string, interval time.Duration) error

WaitForHealthz polls baseURL+"/v1/healthz" until it returns 2xx or the context is cancelled. interval controls how often the probe retries between attempts. Callers are responsible for setting an appropriate context deadline (e.g. 10s during onboarding).

Types

type SpawnOptions

type SpawnOptions struct {
	Executable string
	Args       []string
	WorkingDir string
	Env        []string
	LogPath    string
}

SpawnOptions describes a detached child process. The child inherits the current environment unless Env is set; both stdout and stderr are written to LogPath (or os.DevNull when LogPath is empty).

type SpawnResult

type SpawnResult struct {
	PID     int
	LogPath string
}

SpawnResult reports the launched child's PID and the resolved log path so the caller can surface where output went.

func SpawnDetached

func SpawnDetached(opts SpawnOptions) (SpawnResult, error)

SpawnDetached starts a background process that survives the parent exiting. Stdout/stderr go to LogPath (created if needed). Used by `tars init` when running in --no-service mode (or on non-darwin systems) to start `tars serve` without blocking.