[wgtmac]

Replace the auth-specific token refresh scheduler with an internal utility that shares one process-lifetime timer and submits due work through a caller-owned Executor.

• Accept borrowed executors through RestCatalog::Make(config, client_factory, auth_executor, metrics_executor) and the optional final argument of AuthSession::MakeOAuth2. Enabling OAuth2 refresh requires an auth executor; otherwise session creation returns InvalidArgument.
• Use the existing RetryRunner to complete each refresh on an executor worker, with up to five HTTP retries and Java's default backoff settings. Submission failure stops the refresh chain. Backoff occupies a worker and may delay session closing.
• Keep cancellation and shutdown scoped to each scheduler. Closing a session cancels its pending refreshes and waits for active refreshes.
• Keep the shared timer alive during static destruction, and reuse shared executor helpers in the regression tests.
• S3-specific tests were not run (ICEBERG_S3=OFF).

[Copilot]

🟡 Changes recommended

Unresolved linking, concurrency, scheduler lifetime, and refresh-dispatch issues block approval.

5 open issues

• Prevent dangling scheduler references in sessions · New
• Synchronize scheduled task handle access · New
• Export scheduler classes for cross-library linking · New
• Forward auth refresh executor through SigV4 manager · New
• Handle refresh task submission failures · New

What changed in this PR

Moves OAuth token-refresh scheduling into a reusable internal utility that dispatches work through an injected executor.

Changes:

• Replaces the auth-specific scheduler with ScheduledExecutor.
• Adds optional executor injection; background refresh is disabled when omitted.
• Migrates scheduler tests and updates build integration.

File	Description
src/​iceberg/​util/​scheduled_executor.cc	Implements delayed dispatch and cancellation.
src/​iceberg/​util/​scheduled_executor_internal.h	Defines scheduler and task handles.
src/​iceberg/​test/​auth_manager_test.cc	Migrates scheduler tests.
src/​iceberg/​cpp20_compatibility_internal.h	Removes the deleted scheduler include.
src/​iceberg/​CMakeLists.txt	Builds the new scheduler.
src/​iceberg/​catalog/​rest/​rest_catalog.h	Exposes optional auth executor injection.
src/​iceberg/​catalog/​rest/​rest_catalog.cc	Configures the auth manager’s executor.
src/​iceberg/​catalog/​rest/​CMakeLists.txt	Removes the old scheduler source.
src/​iceberg/​catalog/​rest/​auth/​token_refresh_scheduler.h	Deletes the old scheduler interface.
src/​iceberg/​catalog/​rest/​auth/​token_refresh_scheduler.cc	Deletes the old scheduler implementation.
src/​iceberg/​catalog/​rest/​auth/​auth_session.h	Documents refresh executor requirements.
src/​iceberg/​catalog/​rest/​auth/​auth_session.cc	Passes the scheduler into session configuration.
src/​iceberg/​catalog/​rest/​auth/​auth_session_internal.h	Adapts refresh scheduling and cancellation.
src/​iceberg/​catalog/​rest/​auth/​auth_manager.h	Adds the executor configuration hook.
src/​iceberg/​catalog/​rest/​auth/​auth_manager.cc	Creates and supplies the scheduler.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Scheduling and teardown races can stop refresh or terminate the process, while rejected submissions can cause a busy loop.

3 open issues

• Race can cancel a newly scheduled refresh successor · New
• Timer-thread teardown can self-join and terminate the process · New
• Expired tokens cause a zero-delay rejection retry loop · New

1 previously missed issue

In code that hasn't changed since last review

Destruction order can invalidate callback state before worker joins

src/​iceberg/​test/​auth_manager_test.cc:704

Shutdown() now joins only the timer thread, not executor workers. A worker can set fired and pause before cv.notify_one(); the waiting thread can observe fired and finish the test, destroying cv before ThreadExecutor's destructor joins that worker. Declare the callback state before the executor so its workers are joined before their captured objects are destroyed.

5 resolved since last review

• Export scheduler classes for cross-library linking
• Synchronize scheduled task handle access
• Prevent dangling scheduler references in sessions
• Handle refresh task submission failures
• Forward auth refresh executor through SigV4 manager

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The asynchronous scheduling and shared-lifetime teardown changes need human validation before approval.

3 open issues

• Timer-thread teardown can self-join and terminate the process
• Race can cancel a newly scheduled refresh successor
• Expired tokens cause a zero-delay rejection retry loop

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Executor rejection recovery resets HTTP retry state, allowing failing token requests to bypass the retry limit indefinitely.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Rejected refresh retries reset attempts and bypass the retry limit

src/​iceberg/​catalog/​rest/​auth/​auth_session_internal.h:242

When submission of an HTTP retry is rejected, this handler reschedules through ScheduleRefreshAfter(), whose callback calls DoRefresh() and resets the HTTP attempt counter to zero. Alternating accepted and rejected submissions while token requests fail can therefore bypass kMaxRetries indefinitely. Retry dispatch of the pending DoRefreshAttempt, preserving its attempt, backoff, and refresh_started_at, while retaining the bounded dispatch-retry backoff.

3 resolved since last review

• Timer-thread teardown can self-join and terminate the process
• Race can cancel a newly scheduled refresh successor
• Expired tokens cause a zero-delay rejection retry loop

_{Review effort: Balanced}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

5 open issues

• This reorders parameters of an exported/public factory (Make), which is a source-breaking change… · New
• Cancellation can be lost in the race where Run() pops a due task (erasing from scheduled_) and… · New
• scheduled_ is not updated when a cancelled task is discarded here. This leaves stale IDs in… · New
• Moving out of std::priority_queue::top() via const_cast is brittle and easy to misreason about… · New
• New behavior is introduced for rejection handling (on_rejected) but the migrated tests in… · New

_{Review effort: Lite}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

11 open issues

• scheduled_ is not updated when a cancelled task is discarded here. This leaves stale IDs in…
• Cancellation can be lost in the race where Run() pops a due task (erasing from scheduled_) and…
• This reorders parameters of an exported/public factory (Make), which is a source-breaking change…
• This changes the parameter ordering of a public exported factory (ICEBERG_REST_EXPORT), which is… · New
• This introduces locals that are never used (inserted, and cancelled is only written then… · New
• This introduces locals that are never used (inserted, and cancelled is only written then… · New
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid… · New
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid… · New
• ScheduledTask is currently copyable (implicit copy ctor/assign). Copying will produce multiple… · New
• New behavior is introduced for rejection handling (on_rejected) but the migrated tests in…
• Moving out of std::priority_queue::top() via const_cast is brittle and easy to misreason about…

_{Review effort: Lite}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

14 open issues

• scheduled_ is not updated when a cancelled task is discarded here. This leaves stale IDs in…
• Cancellation can be lost in the race where Run() pops a due task (erasing from scheduled_) and…
• This reorders parameters of an exported/public factory (Make), which is a source-breaking change…
• This reorders RestCatalog::Make parameters and removes the prior `(config, metrics_executor,… · New
• Shutdown() is called from both ScheduledExecutor::~ScheduledExecutor() and… · New
• ScheduledTask::Cancel() mutates state_/id_ without synchronization. If a ScheduledTask… · New
• ScheduledTask is currently copyable (implicit copy ctor/assign). Copying will produce multiple…
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid…
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid…
• This introduces locals that are never used (inserted, and cancelled is only written then…
• This introduces locals that are never used (inserted, and cancelled is only written then…
• This changes the parameter ordering of a public exported factory (ICEBERG_REST_EXPORT), which is…
• New behavior is introduced for rejection handling (on_rejected) but the migrated tests in…
• Moving out of std::priority_queue::top() via const_cast is brittle and easy to misreason about…

_{Review effort: Lite}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

18 open issues

• scheduled_ is not updated when a cancelled task is discarded here. This leaves stale IDs in…
• Cancellation can be lost in the race where Run() pops a due task (erasing from scheduled_) and…
• This reorders parameters of an exported/public factory (Make), which is a source-breaking change…
• This changes the exported RestCatalog::Make signature by reordering parameters and adding… · New
• The structured binding element inserted is unused. With common warning sets (e.g., `-Wall… · New
• cancelled is intentionally used only for its lifetime (to release captures outside the lock), but… · New
• ScheduledTask is implicitly copyable, but IsValid() only checks that the handle still has an id… · New
• ScheduledTask::Cancel() mutates state_/id_ without synchronization. If a ScheduledTask…
• Shutdown() is called from both ScheduledExecutor::~ScheduledExecutor() and…
• This reorders RestCatalog::Make parameters and removes the prior `(config, metrics_executor,…
• ScheduledTask is currently copyable (implicit copy ctor/assign). Copying will produce multiple…
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid…
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid…
• This introduces locals that are never used (inserted, and cancelled is only written then…
• This introduces locals that are never used (inserted, and cancelled is only written then…
• This changes the parameter ordering of a public exported factory (ICEBERG_REST_EXPORT), which is…
• New behavior is introduced for rejection handling (on_rejected) but the migrated tests in…
• Moving out of std::priority_queue::top() via const_cast is brittle and easy to misreason about…

_{Review effort: Lite}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

21 open issues

• scheduled_ is not updated when a cancelled task is discarded here. This leaves stale IDs in…
• Cancellation can be lost in the race where Run() pops a due task (erasing from scheduled_) and…
• This reorders parameters of an exported/public factory (Make), which is a source-breaking change…
• This change reorders RestCatalog::Make parameters (moving metrics_executor from position 2 to… · New
• SharedTimerState::Schedule doesn’t check shutdown_. If Shutdown() has been called, Run()… · New
• ScheduledTask is implicitly copyable, but IsValid() only checks that the handle still has an id…
• cancelled is intentionally used only for its lifetime (to release captures outside the lock), but…
• The structured binding element inserted is unused. With common warning sets (e.g., `-Wall…
• This changes the exported RestCatalog::Make signature by reordering parameters and adding…
• ScheduledTask::Cancel() mutates state_/id_ without synchronization. If a ScheduledTask…
• Shutdown() is called from both ScheduledExecutor::~ScheduledExecutor() and…
• This reorders RestCatalog::Make parameters and removes the prior `(config, metrics_executor,…
• ScheduledTask is currently copyable (implicit copy ctor/assign). Copying will produce multiple…
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid…
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid…
• This introduces locals that are never used (inserted, and cancelled is only written then…
• This introduces locals that are never used (inserted, and cancelled is only written then…
• This changes the parameter ordering of a public exported factory (ICEBERG_REST_EXPORT), which is…
• New behavior is introduced for rejection handling (on_rejected) but the migrated tests in…
• Moving out of std::priority_queue::top() via const_cast is brittle and easy to misreason about…

And 1 more that still need to be addressed.

_{Review effort: Lite}

[Copilot]

🔵 Needs a closer look

Shared-timer teardown, cross-thread shutdown, and borrowed-executor lifetimes warrant final human concurrency review.

No open issues 🎉

21 resolved since last review

• scheduled_ is not updated when a cancelled task is discarded here. This leaves stale IDs in…
• Cancellation can be lost in the race where Run() pops a due task (erasing from scheduled_) and…
• This reorders parameters of an exported/public factory (Make), which is a source-breaking change…
• SharedTimerState::Schedule doesn’t check shutdown_. If Shutdown() has been called, Run()…
• This change reorders RestCatalog::Make parameters (moving metrics_executor from position 2 to…
• ScheduledTask is implicitly copyable, but IsValid() only checks that the handle still has an id…
• cancelled is intentionally used only for its lifetime (to release captures outside the lock), but…
• The structured binding element inserted is unused. With common warning sets (e.g., `-Wall…
• This changes the exported RestCatalog::Make signature by reordering parameters and adding…
• ScheduledTask::Cancel() mutates state_/id_ without synchronization. If a ScheduledTask…
• Shutdown() is called from both ScheduledExecutor::~ScheduledExecutor() and…
• This reorders RestCatalog::Make parameters and removes the prior `(config, metrics_executor,…
• ScheduledTask is currently copyable (implicit copy ctor/assign). Copying will produce multiple…
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid…
• The previous TokenRefreshScheduler::Instance() was intentionally leaked to avoid…
• This introduces locals that are never used (inserted, and cancelled is only written then…
• This introduces locals that are never used (inserted, and cancelled is only written then…
• This changes the parameter ordering of a public exported factory (ICEBERG_REST_EXPORT), which is…
• New behavior is introduced for rejection handling (on_rejected) but the migrated tests in…
• Moving out of std::priority_queue::top() via const_cast is brittle and easy to misreason about…

And 1 more resolved.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Shared-timer lifetime, borrowed executors, and concurrent shutdown guarantees warrant final human concurrency review.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

3 open issues

• This changes the public RestCatalog::Make parameter order in a way that breaks existing… · New
• inserted is never used. With common warning levels (and especially with -Werror), this may fail… · New
• cancelled is not referenced, which can trigger an unused-variable warning. If the intent is to… · New

_{Review effort: Lite}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

6 open issues

• inserted is never used. If the project builds with -Werror (common in CI), this can fail… · New
• This changes the public RestCatalog::Make parameter order in a way that breaks existing…
• This changes the positional argument order for a public factory (metrics_executor moved from 2nd… · New
• cancelled is not referenced, which can trigger an unused-variable warning. If the intent is to…
• inserted is never used. With common warning levels (and especially with -Werror), this may fail…
• submissions is mutated on the timer thread and read on the test thread. While current waits on… · New

_{Review effort: Lite}

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

10 open issues

• Reordering RestCatalog::Make parameters is a source-breaking change and can also silently… · New
• inserted is never used. If the project builds with -Werror (common in CI), this can fail…
• This changes the public RestCatalog::Make parameter order in a way that breaks existing…
• std::multimap does not guarantee preserving insertion order among equivalent keys, but the… · New
• std::multimap does not guarantee preserving insertion order among equivalent keys, but the… · New
• This changes the positional argument order for a public factory (metrics_executor moved from 2nd…
• cancelled is not referenced, which can trigger an unused-variable warning. If the intent is to…
• inserted is never used. With common warning levels (and especially with -Werror), this may fail…
• Minor readability/style issue: std::move (*on_submission) is unusual spacing and easy to misread.… · New
• submissions is mutated on the timer thread and read on the test thread. While current waits on…

_{Review effort: Lite}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[wgtmac]

@lishuxu @plusplusjiajia Could you help review this?