Skip to content

Coordinate file-backed OAuth refreshes and guard uncertain outcomes - #7396

Draft
yaoharry wants to merge 3 commits into
databricks:mainfrom
yaoharry:harry-yao/file-backed-oauth-cache-transactions-20261107
Draft

yaoharry wants to merge 3 commits into
databricks:mainfrom
yaoharry:harry-yao/file-backed-oauth-cache-transactions-20261107

Conversation

@yaoharry

@yaoharry yaoharry commented Nov 7, 2026 •

Copy link
Copy Markdown

Changes

Concurrent CLI processes sharing a file-backed OAuth cache can overwrite newer credentials. A successful remote refresh followed by a failed local write can also cause a later client to replay the spent credential. Use one lease on the canonical effective cache file, reload/recheck before exchange, and publish staged changes across login/logout and legacy mirrors.

Record a consumed refresh generation before exchange in a synced append-only companion. Bind successful responses to the exact cache publication, attempt nonce and written keys. Fresh cooperating clients refrain from reusing uncertain generations; successful nonrotating responses open only their proven entry epochs. Preserve still-valid access-token fallback and access-only login; explicit force cannot bypass an uncertain generation. Recovery errors retain actionable guidance and explicit JSON output. Guidance preserves profile precedence or known workspace/account host scope using static builders; it performs no discovery and never masks the typed recovery cause for an invalid host.

This explicitly attributed file-backed alternative is related to #6759. It retains Vivek1106-04's Unix/Windows OS adapters byte-for-byte and original co-author credit.

Why

Two processes can share one cache while using different HOME directories. A provider can also accept a refresh before the local replacement is committed. In that second case, the old file can otherwise cause a fresh client to replay the spent credential. A serialized write alone does not close that window.

The companion preserves consumed generations across cooperating-process loss. An invalid or partial append blocks automatic refresh and can require recovery; there is no automatic file repair. Lost replacement credentials cannot be recreated. Independent cache copies without the companion, deleted/rolled-back metadata, power/OS loss, remote filesystems, old nonparticipating clients and keyring asynchronous behavior remain outside this file-only guarantee. Adoption is required before installed clients benefit. History is retained without GC; startup and each lease reread the retained log.

Tests

Local normal required legs passed with Go1.27.3, FIPSv1.0.0, original timeouts and no automatic reruns:

Scope Passed Failed Default skips Exit
Full root 12,100 0 134 0
Full acceptance 3,468 0 5 0
Full tools 82 0 0 0

Zero failed or incomplete packages. Normal fmt/checks/lint exit0. Complete auth/storage/u2m/cmd-auth owning modules pass738 leaves; this overlaps root rather than adding to its count. The original byte-exact two-case diagnostic changes from healthy PASS/replay RED to both PASS; its semantic scope overlaps the maintained regression.

Real FileStore/OS-lease controls cover aliases, captured retirement and future-owner negatives, nullable/access-only results, malformed frames and zero-call preparation failure, encoding/context/I/O failures, and first-denial preservation with one HTTP request across two clients. Two deterministic child-process losses occur after cache publication but before completion, including a byte-identical nonrotating result. Existing assertions, budgets, timeouts and default skips remain.

Windows/amd64 and Darwin/arm64 compile all3 owning packages; runtime proof is Linux only. Tests use fake HOME/config, read-only source/dependencies and loopback-only fake OAuth/services. The root leg's existing anonymous public GitHub metadata reads retain real TLS through the reviewed allowlist; auth/provider egress is blocked. Linux keyring acceptance uses its supported unavailable-backend branch, never the user's OS service. Earlier failed setup/metadata and narrow output receipts remain preserved; no CI, deployment or observed-episode result is claimed.

This PR was written with Codex assistance.

Reload and recheck the canonical file store under one operation-context lease,
then atomically publish the staged map. Coordinate login, logout, pending login
and legacy mirror writers while preserving main's secure backend and Store API.

Build on the OS locking foundation from Vivek1106-04 in related PR databricks#6759;
lock_unix.go and lock_windows.go are copied byte-identically. This is a
file-backed alternative proposed against main from an owned branch.

Co-authored-by: Vivek1106-04 <gangavarapu.0104@gmail.com>
Signed-off-by: Harry Yao <harry.yao@databricks.com>
@github-actions github-actions Bot added the DABs DABs related issues label Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Thanks for the contribution! This pull request was opened from a fork.

If you're a member of the Databricks organization, please request access to the cli-contrib team and open your pull request from a branch in this repository instead of a fork — fork PRs don't run integration tests automatically and have reduced CI access.

If you're an external contributor, no action is needed; a maintainer will review your pull request.

Harry Yao added 2 commits November 7, 2026 10:58
Signed-off-by: Harry Yao <harry.yao@databricks.com>
Persist consumed generations before exchange using a synced append-only
companion under the existing canonical-cache lease. Bind successful responses
to their exact cache publication and written-key epochs, preserving aliases,
access-only login, valid-access fallback and explicit force safeguards.

Keep consumed tombstones and fail closed on incomplete metadata. Preserve
initiating provider denial handling and render guarded recovery errors through
the existing actionable/JSON paths.

Signed-off-by: Harry Yao <harry.yao@databricks.com>
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

An authorized user can trigger integration tests manually by following the instructions below:

Trigger:
go/deco-tests-run/cli

Inputs:

  • PR number: 7396
  • Commit SHA: 7ab1fc01fb128c9181fc7937256a10f9c8806d64

Checks will be approved automatically on success.

@yaoharry yaoharry changed the title Serialize file-backed OAuth refreshes and cache writes Coordinate file-backed OAuth refreshes and guard uncertain outcomes Nov 7, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

DABs DABs related issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant