broker mode schema changes

[akshaydeo]

Summary

Adds a broker clustering mode to the transport configuration schema, enabling deployments on platforms that lack peer-to-peer connectivity (e.g. Cloud Run) to route cluster traffic through a central broker process instead of using the default memberlist gossip mesh.

Changes

• Added a type field to the cluster config with two options: "mesh" (default, existing peer-to-peer behavior via memberlist gossip) and "broker" (routes all cluster traffic through a central broker process).
• Added a broker config object with the following fields:
  • address (required): host:port of the broker that nodes dial.
  • tls: Whether to dial the broker over TLS.
  • auth_token: Optional shared secret sent on connect.
  • listen_port: Port the broker process serves on (default: 50051).

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Validate the schema accepts and rejects configurations as expected:

# Verify schema changes are valid
go test ./transports/...

Example valid broker config:

{
  "enabled": true,
  "type": "broker",
  "broker": {
    "address": "broker.internal:50051",
    "tls": true,
    "auth_token": "secret",
    "listen_port": 50051
  }
}

• type: "mesh" should continue to work without any broker block.
• type: "broker" without an address field should fail schema validation.
• broker block with unknown fields should fail due to additionalProperties: false.

Breaking changes

• Yes
• No

Security considerations

The auth_token field is a shared secret transmitted on broker connection. Ensure this value is stored and passed securely (e.g. via environment variable or secrets manager) and that TLS is enabled when using auth_token over untrusted networks.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0dc6e034-afc3-4712-9339-a29e80726e8a

📥 Commits

Reviewing files that changed from the base of the PR and between 4de215a and 35f562f.

📒 Files selected for processing (1)

• transports/config.schema.json

🚧 Files skipped from review as they are similar to previous changes (1)

• transports/config.schema.json

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added support for a new "broker" clustering mode alongside the existing mesh option.
  • Added broker configuration options: broker address (required), TLS settings, optional authentication token, and listen port.
  • Default clustering mode remains "mesh".

Walkthrough

This PR extends the transport configuration schema to add a cluster_config.type enum (defaults to "mesh") and a cluster_config.broker object that declares broker-mode fields: required address, optional tls, optional auth_token, optional listen_port, and additionalProperties: false.

Changes

Broker Clustering Configuration

Layer / File(s)	Summary
Mode selector and docs transports/config.schema.json	Adds cluster_config.type string enum with values "mesh" and "broker", defaulting to "mesh"; documents behavioral distinction between mesh gossip and broker-routed clustering.
Broker connection and server contract transports/config.schema.json	Introduces cluster_config.broker object schema: required address (string), optional tls (object), optional auth_token (string), optional listen_port (integer), and additionalProperties: false to forbid unspecified fields.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 A broker path through clustered ways,
Mesh and broker now share the maze,
With address set and TLS snug,
A token whispers — secure and smug.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'broker mode schema changes' directly describes the main change in the pull request—adding broker mode support to the schema.
Description check	✅ Passed	The description comprehensively covers the PR template, including summary, changes, type of change, affected areas, testing instructions, security considerations, and checklist items.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 05-14-broker_mode_schema_changes

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[akshaydeo]

• broker docs #3515
• broker mode schema changes #3509 👈 (View in Graphite)
• streaming calls support for hanress #3507
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Confidence Score: 5/5

Schema-only change that adds new optional fields with no breaking modifications to existing cluster config; existing mesh configs are unaffected.

The change is purely additive to a JSON Schema definition. Existing cluster_config consumers continue to work unchanged, and the new broker block is optional at the schema level. The only finding is a minor inconsistency in how the listen_port default is expressed.

No files require special attention beyond transports/config.schema.json, which contains the only changes.

Important Files Changed

Filename	Overview
transports/config.schema.json	Adds type field (mesh/broker enum) and a broker sub-object to cluster_config; minor inconsistency where listen_port default is only in the description string rather than the JSON Schema default keyword

_{Reviews (2): Last reviewed commit: "broker mode schema changes" | Re-trigger Greptile}

[coderabbitai]

🧹 Nitpick comments (1)

transports/config.schema.json (1)

3421-3446: ⚡ Quick win

Consider adding conditional validation and aligning defaults.

A few observations on the broker object:

1. auth_token: Other sensitive fields in this schema document env.VAR_NAME support (e.g., proxy_config.password). Consider adding this to the description to discourage hardcoding secrets.

2. listen_port: The description says "(default: 50051)" but there's no default property in the schema. This inconsistency could cause tooling or documentation drift.

3. Conditional requirement: When type: "broker", the broker object should likely be required. Consider adding an if/then block (similar to scim_config) to enforce this at schema level.

Suggested improvements

         "broker": {
           "type": "object",
           "description": "Broker settings, used when type is 'broker'",
           "properties": {
             "address": {
               "type": "string",
               "description": "host:port of the broker that nodes dial"
             },
             "tls": {
               "type": "boolean",
-              "description": "Whether to dial the broker over TLS"
+              "description": "Whether to dial the broker over TLS",
+              "default": false
             },
             "auth_token": {
               "type": "string",
-              "description": "Optional shared secret sent on connect"
+              "description": "Optional shared secret sent on connect. Supports env.VAR_NAME for environment variable reference."
             },
             "listen_port": {
               "type": "integer",
               "minimum": 1,
               "maximum": 65535,
-              "description": "Port the broker process serves on (default: 50051)"
+              "description": "Port the broker process serves on",
+              "default": 50051
             }
           },
           "required": ["address"],
           "additionalProperties": false
         }

For conditional validation, add at the end of cluster_config:

"if": {
  "properties": { "type": { "const": "broker" } },
  "required": ["type"]
},
"then": {
  "required": ["broker"]
}

As per coding guidelines, config.schema.json is the authoritative source—ensuring schema completeness helps keep handlers and docs aligned.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@transports/config.schema.json` around lines 3421 - 3446, The broker object
schema is missing sensitive-env guidance, a declared default for listen_port,
and conditional validation to require broker when type is "broker"; update the
broker.properties.auth_token description to mention env.VAR_NAME support (like
proxy_config.password), add "default": 50051 to broker.properties.listen_port,
and add an if/then block under the parent cluster_config (mirroring scim_config)
that checks if properties.type const "broker" and then requires ["broker"] so
the broker object is mandatory when type is "broker".

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@transports/config.schema.json`:
- Around line 3421-3446: The broker object schema is missing sensitive-env
guidance, a declared default for listen_port, and conditional validation to
require broker when type is "broker"; update the broker.properties.auth_token
description to mention env.VAR_NAME support (like proxy_config.password), add
"default": 50051 to broker.properties.listen_port, and add an if/then block
under the parent cluster_config (mirroring scim_config) that checks if
properties.type const "broker" and then requires ["broker"] so the broker object
is mandatory when type is "broker".

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bd659c46-a604-4ce3-99a6-c6a1b146c227

📥 Commits

Reviewing files that changed from the base of the PR and between 99651d2 and 4de215a.

📒 Files selected for processing (1)

• transports/config.schema.json

[akshaydeo]

Merge activity

• May 15, 5:18 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 15, 5:19 AM UTC: @akshaydeo merged this pull request with Graphite.

The base branch was changed.