openapi(dm): support task timezone

[OliverS929]

What problem does this PR solve?

Issue Number: ref #12756

DM task configuration supports timezone, but this option is not available
through OpenAPI.

What is changed and how it works?

• Add an optional timezone field to the OpenAPI task schema.
• Validate it with DM's existing time-zone parser.
• Preserve it when converting between OpenAPI tasks and subtask configurations.
• Keep the existing downstream database time zone behavior when the field is
  omitted or empty.

The DST fall-back repeated-hour behavior observed during testing is an existing
DM runtime limitation, not introduced by OpenAPI. This PR only aligns the
OpenAPI capability, and changing the runtime behavior is out of scope.

Check List

Tests

• Unit test
• Manual test (add detailed scripts or steps below)

Manual testing with DM, MySQL 8.4, and TiDB covered valid, invalid, and omitted
time zones, create and readback, update rejection, downstream-default behavior,
and full and incremental replication.

Questions

Will it cause performance regression or break compatibility?

No. The field is optional, and omitted or empty values preserve the existing
behavior.

Do you need to update user documentation, design documentation or monitoring documentation?

No additional documentation update is needed.

Release note

Support configuring the DM task time zone through OpenAPI.

Summary by CodeRabbit

• New Features

  • Tasks now support an optional timezone field that is validated upon submission. Timezone is immutable after task creation and defaults to database configuration when omitted.

• Documentation

  • Updated API specification to document the timezone property and its fallback behavior.

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign benjamin2037 for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• dm/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1e775f27-05cf-452e-afc3-e1b3c3a2dde0

📥 Commits

Reviewing files that changed from the base of the PR and between 4880637 and 67c0347.

📒 Files selected for processing (11)

• dm/config/task_converters.go
• dm/config/task_converters_test.go
• dm/master/openapi_controller_test.go
• dm/master/openapi_view_test.go
• dm/openapi/fixtures/task.go
• dm/openapi/gen.server.go
• dm/openapi/gen.types.go
• dm/openapi/spec/dm.yaml
• dm/openapi/task.go
• dm/openapi/task_test.go
• dm/syncer/syncer_test.go

---

📝 Walkthrough

Walkthrough

The change adds an optional task timezone to the OpenAPI model, validates timezone values, propagates timezones during task conversion, returns them in API responses, and rejects timezone changes during configuration updates.

Changes

Task timezone support

Layer / File(s)	Summary
API contract and timezone validation dm/openapi/spec/dm.yaml, dm/openapi/gen.types.go, dm/openapi/gen.server.go, dm/openapi/task.go, dm/openapi/task_test.go, dm/openapi/fixtures/task.go	The Task API defines an optional timezone field. Task.Adjust validates non-empty values and accepts empty values for downstream defaults.
Timezone conversion mapping dm/config/task_converters.go, dm/config/task_converters_test.go	Task timezone values propagate to subtask configurations and return from non-empty subtask timezones. Source database configuration cloning is preserved.
Task API propagation dm/master/openapi_controller_test.go, dm/master/openapi_view_test.go	Creation, retrieval, listing, and status responses preserve the task timezone. Invalid timezone creation is rejected.
Immutable timezone updates dm/syncer/syncer_test.go, dm/master/openapi_view_test.go	Syncer configuration updates reject timezone changes. The API returns ErrSchedulerSubTaskCfgUpdate and retains the original timezone.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant API Client
  participant Task.Adjust
  participant OpenAPITaskToSubTaskConfigs
  participant Scheduler
  API Client->>Task.Adjust: Submit task with timezone
  Task.Adjust-->>API Client: Accept valid timezone or return ErrConfigInvalidTimezone
  Task.Adjust->>OpenAPITaskToSubTaskConfigs: Adjusted task
  OpenAPITaskToSubTaskConfigs->>Scheduler: Subtask configuration with timezone
  Scheduler-->>API Client: Task response with timezone

Loading

Possibly related PRs

• pingcap/tiflow#12777: Covers the same task timezone support changes across the same conversion, API, and test areas.

Poem

A rabbit hops through timezone skies,
From task to subtask, value flies.
Valid zones pass; bad ones flee,
Fixed zones stay where they should be.
The API returns the time just right.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding task timezone support to the DM OpenAPI.
Description check	✅ Passed	The description covers the problem, issue reference, implementation, tests, compatibility, documentation, and release note.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

Error: can't load config: unsupported version of the configuration: "" See https://golangci-lint.run/docs/product/migration-guide for migration instructions
The command is terminated due to an error: can't load config: unsupported version of the configuration: "" See https://golangci-lint.run/docs/product/migration-guide for migration instructions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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