Skip to content

Support persistent default listen-addr for spacetime start#4576

Open
0monish wants to merge 1 commit intoclockworklabs:masterfrom
0monish:feature/start-listen-addr-config
Open

Support persistent default listen-addr for spacetime start#4576
0monish wants to merge 1 commit intoclockworklabs:masterfrom
0monish:feature/start-listen-addr-config

Conversation

@0monish
Copy link

@0monish 0monish commented Mar 6, 2026

Description of Changes

This change allows spacetime start to use a project-configured default listen address from spacetime.json.

Behavior precedence is now:

  1. Explicit CLI flag, such as spacetime start --listen-addr 127.0.0.1:5000
  2. listen-addr from spacetime.json
  3. Built-in default 0.0.0.0:3000

Example:

{
  "listen-addr": "0.0.0.0:4000"
}

With that config in place, spacetime start will start on 0.0.0.0:4000 unless --listen-addr is passed explicitly.

Implementation details:

  • spacetime start now checks project config before forwarding to the standalone binary.
  • Config lookup uses the existing spacetime.json discovery behavior, including parent-directory search and spacetime.local.json layering.
  • The forwarded argument path preserves CLI precedence over config.
  • Added unit tests covering detection of explicit --listen-addr and -l forms so config is only injected when the user did not already provide a listen address.
  • Updated standalone config documentation to describe the new listen-addr behavior and precedence.

This is backward compatible:

  • users without config still get 0.0.0.0:3000
  • existing scripts that pass --listen-addr continue to behave the same
  • the feature is project-local and works with the existing config-driven workflow

API and ABI breaking changes

None.

This change does not modify any public API or ABI. It only adds an additional configuration source for an existing CLI option while preserving current defaults and CLI override behavior.

Expected complexity level and risk

Complexity: 2/5

This is a small, localized CLI behavior change.

The main interaction point is config precedence between forwarded CLI arguments and project configuration. The implementation is low risk because it:

  • preserves the existing standalone default when config is absent
  • preserves explicit CLI --listen-addr and -l precedence
  • reuses the existing spacetime.json discovery and layering behavior rather than introducing a new config system

The main thing reviewers may want to sanity-check is that the new config-backed behavior only applies when the user did not explicitly pass a listen address.

Testing

Completed:

  • cargo fmt
  • cargo check -p spacetimedb-cli
  • cargo test -p spacetimedb-cli subcommands::start::tests
  • cargo clippy -p spacetimedb-cli --all-targets

Reviewer checks:

  • Run spacetime start without spacetime.json and confirm it still binds to 0.0.0.0:3000
  • Add "listen-addr": "0.0.0.0:4000" to spacetime.json, run spacetime start, and confirm it binds to 0.0.0.0:4000
  • Run spacetime start --listen-addr 127.0.0.1:5000 with config present and confirm the CLI flag still wins

Allow \`spacetime start\` to use a project-configured default listen address
from \`spacetime.json\`, with proper precedence: CLI flag > config > built-in default.

- Add \`has_listen_addr_arg()\` helper to detect explicit --listen-addr or -l
- Add \`resolve_listen_addr_from_config()\` to load listening address from config
- Inject config-backed address only when user didn't pass explicit CLI flag
- Add 12 unit tests covering all argument detection edge cases
- Update standalone config documentation with precedence and examples

Changes are backward compatible: existing users without config still get
0.0.0.0:3000, and explicit CLI flags continue to take precedence.
@CLAassistant
Copy link

CLAassistant commented Mar 6, 2026

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants