feat: Add Reason Variable to Failovers

[zawadzkidiana]

What changed?

• Added --reason flag (short form -r) to the cadence domain failover command
• Added Reason field to FailoverDomainRequest and UpdateDomainRequest types
• Updated the server-side handler to store the reason in FailoverEvent
• Made sure the reason flows through from CLI to database in the failover history
• Updated the ToUpdateDomainRequest mapper to pass the reason through

Why?
We needed better visibility into why failovers were happening. Right now when you look at failover history you can see when and where failovers happened, but not why. This makes it hard to debug issues or understand patterns. With this change, operators can provide context like "planned maintenance", "emergency DR", "testing", etc. and it gets stored with the failover event. Makes it way easier to go back and understand what was going on during production incidents.

How did you test it?

• Verified the CLI flag shows up in help output: ./cadence domain failover --help
• Ran make bins - everything compiles
• Ran make lint - passes
• Ran go test ./tools/cli/... - all CLI tests pass
• Ran go test ./common/domain/... - all domain handler tests pass
• Manually checked that the flag accepts strings

The flow from CLI to database is tested through the existing test suite. The reason goes: CLI flag → FailoverDomainRequest → UpdateDomainRequest → FailoverEvent → gets stored in domain data.

Potential risks
Pretty low risk overall since it's backward compatible. The reason field is optional in all the types so old clients can still talk to new servers and vice versa. If you don't provide a reason it just stays empty.

Main thing to watch would be if someone passes in a really long reason string - it goes into domain data which is stored as a map, so there might be size limits there. But that's more of an edge case than a real risk.

Also if someone is relying on the exact format of the FailoverEvent JSON in domain data, this adds a new field. But since it's optional and has the omitempty tag, it shouldn't break anything.

Release notes

Scope is type system, CLI, and domain handler, but the thrift and proto type mappers for FailoverDomainRequest are not updated.

Added optional --reason flag to domain failover command. This lets you specify why a failover is happening and the reason gets stored in the failover history. No migration or schema changes needed.

Documentation Changes
hould probably update the CLI docs to mention the new --reason flag and show some examples of how to use it. The flag shows up in --help but would be good to have it in the actual documentation too.

[timl3136]

lgtm, maybe we can make the pr title more descriptive.

[zawadzkidiana]

Re-running 1 failed Golang integratiuon test with sqlite (pull_request); all other tests pass.

[zawadzkidiana]

Github outage is likely cause of sqlite integration error; will re-run test again after problem is resolved.

[gitar-bot]

Code Review ⚠️ Changes requested 0 resolved / 1 findings

The Reason field is correctly added to the type system, CLI, and domain handler, but the thrift and proto type mappers for FailoverDomainRequest are not updated — the reason will be silently dropped when requests go through RPC, which is the standard production path.

⚠️ Bug: Reason field missing from thrift and proto type mappers

📄 common/types/shared.go:1790

The new Reason field added to FailoverDomainRequest in common/types/shared.go is not mapped in the thrift or proto type mapper layers:

1. Thrift mapper (common/types/mapper/thrift/shared.go lines 1618-1639): Both FromFailoverDomainRequest and ToFailoverDomainRequest only map DomainName, DomainActiveClusterName, and ActiveClusters — the new Reason field is silently dropped.

2. Proto mapper (common/types/mapper/proto/api.go lines 4526-4546): Same issue — Reason is not included in either direction.

Impact: When a client sends a failover request over RPC (the normal production path), the reason will be lost. The CLI calls frontendClient.FailoverDomain() which goes through thrift serialization. The thrift wrapper at service/frontend/wrappers/thrift/api_generated.go calls thrift.ToFailoverDomainRequest() to convert the incoming request, which drops the Reason field. The feature will only work when the CLI uses the direct domainHandler path (when frontendClient is nil), which is not the standard deployment mode.

Both mapper files need to be updated to include Reason in the FailoverDomainRequest field mapping in both directions (To/From).

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}