feat(spec)!: standardize route hostnames (#199)

Replace domain and wildcard_suffix with routes[].hostname in the onebox.run/v2 contract, retain immutable v1 schema URLs, and migrate v1 release snapshots only for lifecycle replay.

BREAKING CHANGE: onebox.run/v2 removes scalar domain routing and routes[].wildcard_suffix; declare exact and literal wildcard values through routes[].hostname.

Author: vishr

.github/workflows/ci.yml

@@ -149,7 +149,7 @@ jobs:
         run: |
           ./ob-smoke${{ runner.os == 'Windows' && '.exe' || '' }} version
           ./ob-smoke${{ runner.os == 'Windows' && '.exe' || '' }} --help
-          ./ob-smoke${{ runner.os == 'Windows' && '.exe' || '' }} schema --out "${{ runner.temp }}/onebox.run-v1.schema.json"
+          ./ob-smoke${{ runner.os == 'Windows' && '.exe' || '' }} schema --out "${{ runner.temp }}/onebox.run-v2.schema.json"
 
   e2e:
     name: End-to-end (Docker)

README.md

@@ -75,15 +75,15 @@ Starting from an existing Compose project, `ob init` writes the first draft.
 This is a complete single-workload project:
 
 ```yaml
-# yaml-language-server: $schema=https://raw.githubusercontent.com/labstack/onebox/main/docs/onebox.run-v1.schema.json
-api_version: onebox.run/v1
+# yaml-language-server: $schema=https://raw.githubusercontent.com/labstack/onebox/main/docs/onebox.run-v2.schema.json
+api_version: onebox.run/v2
 app: shop
 environments:
   production:
     server: root@203.0.113.10
 image: ghcr.io/acme/shop:1.4.0
-domain: shop.example.com
-port: 3000
+routes:
+  - {hostname: shop.example.com, port: 3000}
 ```
 
 It derives the application container, Traefik routing and TLS, release layout

cmd/ob-docgen/main.go

@@ -9,7 +9,7 @@
 //
 // So this program is the only writer of `site/src/content/docs/reference/`
 // — the field pages, `drivers.mdx`, `errors.mdx` and `cli.mdx` — and of the
-// schema published at `site/public/onebox.run-v1.schema.json`. Those pages carry
+// schema published at `site/public/onebox.run-v2.schema.json`. Those pages carry
 // a generated marker,
 // which `--check` reads in both directions: it fails when a page differs from
 // what this binary would produce, and when a marked page survives that no
@@ -67,7 +67,7 @@ func main() {
 		os.Exit(1)
 	}
 	schema = append(schema, '\n')
-	publicFiles := map[string]string{"onebox.run-v1.schema.json": string(schema)}
+	publicFiles := map[string]string{"onebox.run-v2.schema.json": string(schema)}
 
 	if check {
 		if err := verify(out, files); err != nil {

cmd/ob-docgen/main_test.go

@@ -278,7 +278,7 @@ func TestUnclaimedTopLevelKeysDocumentTheirSubtree(t *testing.T) {
 		t.Fatalf("cannot render: %v", err)
 	}
 	page := pages["fields/top-level.mdx"]
-	for _, path := range []string{"routes[].domain", "health.http", "image.reference", "build.context"} {
+	for _, path := range []string{"routes[].hostname", "health.http", "image.reference", "build.context"} {
 		if !strings.Contains(page, "`"+path+"`") {
 			t.Errorf("top-level.mdx does not document %q", path)
 		}
@@ -318,12 +318,12 @@ func TestPublishedSchemaMatchesTheCheckedInCopy(t *testing.T) {
 	}
 	// Skipping on a read failure would turn "someone moved the file" into a
 	// passing test, which is the drift this exists to catch.
-	onDisk, err := os.ReadFile(filepath.Join("..", "..", "docs", "onebox.run-v1.schema.json"))
+	onDisk, err := os.ReadFile(filepath.Join("..", "..", "docs", "onebox.run-v2.schema.json"))
 	if err != nil {
 		t.Fatalf("the checked-in schema must be readable: %v", err)
 	}
 	if strings.TrimSpace(string(generated)) != strings.TrimSpace(string(onDisk)) {
-		t.Error("the published schema differs from docs/onebox.run-v1.schema.json")
+		t.Error("the published schema differs from docs/onebox.run-v2.schema.json")
 	}
 }
 

cmd/ob/commands_test.go

@@ -63,7 +63,7 @@ func writeProject(t *testing.T) string {
 	t.Helper()
 	dir := t.TempDir()
 	obYAML := `
-api_version: onebox.run/v1
+api_version: onebox.run/v2
 app: demo
 environments: { production: { server: deploy@example.invalid } }
 workloads:
@@ -102,7 +102,7 @@ func TestValidateOK(t *testing.T) {
 func TestPreflightBlocksDeploy(t *testing.T) {
 	dir := writeProject(t)
 	obYAML := `
-api_version: onebox.run/v1
+api_version: onebox.run/v2
 app: demo
 environments: { production: { server: deploy@example.invalid } }
 workloads:

cmd/ob/doctor_test.go

@@ -31,7 +31,7 @@ func doctorTestDependencies(t *testing.T) doctorDependencies {
 	oldBinary := filepath.Join(oldDir, "ob")
 	currentBinary := filepath.Join(currentDir, "ob")
 	cfg := &app.Spec{
-		APIVersion: "onebox.run/v1",
+		APIVersion: "onebox.run/v2",
 		Name:       "demo",
 		Environments: map[string]app.Environment{
 			"production": {
@@ -195,7 +195,7 @@ func TestDoctorReportsIncompatibleProjectPolicy(t *testing.T) {
 	deps := doctorTestDependencies(t)
 	deps.loadConfig = func(string) (*app.Spec, error) {
 		return &app.Spec{
-			APIVersion: "onebox.run/v1",
+			APIVersion: "onebox.run/v2",
 			Environments: map[string]app.Environment{
 				"production": {Policy: app.Policy{MinOneboxVersion: "v2027.1.0"}},
 			},

cmd/ob/init.go

@@ -98,7 +98,7 @@ func runInit(ctx context.Context, cmd *cobra.Command, g *globalFlags) error {
 	// errors from the moment the file exists rather than after someone finds
 	// out it could.
 	fmt.Fprintf(&b, "# yaml-language-server: $schema=%s\n", app.SchemaID)
-	b.WriteString("api_version: onebox.run/v1\n")
+	b.WriteString("api_version: onebox.run/v2\n")
 	fmt.Fprintf(&b, "app: %s\n", application)
 	b.WriteString("environments:\n  production:\n    server: deploy@CHANGE-ME\n")
 	b.WriteString("workloads:\n")

cmd/ob/init_test.go

@@ -48,7 +48,7 @@ func TestInitClassifiesAndDoctors(t *testing.T) {
 	}
 	y := string(b)
 	for _, want := range []string{
-		"api_version: onebox.run/v1",
+		"api_version: onebox.run/v2",
 		"server: deploy@CHANGE-ME",
 		"workloads:",
 		"role: application",

cmd/ob/main_test.go

@@ -8,14 +8,14 @@ import (
 	"testing"
 )
 
-const mainTestProject = `api_version: onebox.run/v1
+const mainTestProject = `api_version: onebox.run/v2
 app: demo
 environments: {production: {server: deploy@example.invalid}}
 image: nginx:1.27
 proxy: {kind: none}
 `
 
-const mainTestBuildProject = `api_version: onebox.run/v1
+const mainTestBuildProject = `api_version: onebox.run/v2
 app: demo
 environments: {production: {server: deploy@example.invalid}}
 workloads:

cmd/ob/ops_contract_test.go

@@ -24,7 +24,7 @@ func writeOpsContractProject(t *testing.T, dir string, encrypted bool) string {
 		}
 	}
 	path := filepath.Join(dir, "project.yml")
-	if err := os.WriteFile(path, []byte(`api_version: onebox.run/v1
+	if err := os.WriteFile(path, []byte(`api_version: onebox.run/v2
 app: shop
 environments:
   production: {server: deploy@example.invalid}
@@ -169,7 +169,7 @@ func TestDestroyConfirmationMismatchIsCancelledBeforeTargetContact(t *testing.T)
 func TestServiceLogsAndExecNDJSONTagChannelsAndTargetKind(t *testing.T) {
 	dir := t.TempDir()
 	config := filepath.Join(dir, "project.yml")
-	if err := os.WriteFile(config, []byte(`api_version: onebox.run/v1
+	if err := os.WriteFile(config, []byte(`api_version: onebox.run/v2
 app: shop
 environments:
   production: {server: deploy@example.invalid}