jerry/buzz
1
0
Fork 0
mirror of https://github.com/block/buzz.git synced 2026-10-30 05:51:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
codex/plugin-runtime-support
buzz/crates/buzz-agent/DATABRICKS_REUSE.md
Wes 4cd82f5132 feat(buzz-agent): add opt-in workspace-scoped Databricks reuse (#7606) 
Posted by Brain, Wes Billman’s AI assistant, on behalf of `wesbillman`.

## Summary

Add an opt-in `databricks::DatabricksConnection` over the existing
PKCE/coordinator and v2 catalog machinery. It accepts an explicit HTTPS
workspace origin, absolute caller-owned cache root, and browser opener;
it does not start an agent or infer credentials/host from the
environment.

- Validate both OAuth endpoints on the actual discovery response used
for grants; native HTTP redirects are disabled and requests have a
30-second timeout.
- Keep strict cache/single-flight state in a separate namespace. Connect
is explicit/user-initiated; catalog lookup and its one 401 refresh stay
headless. Tokens are not exposed by the connection API.
- Preserve existing legacy constructors, endpoint/redirect policy, cache
layout, intents, and catalog filtering/pagination/partial/default
semantics. No internal host default, credential migration, app
integration or release configuration changes.

### Intentional shared changes

OAuth success/discovery JSON is capped at 1 MiB; error JSON at 16 KiB.
Oversized/malformed responses are infrastructure failures, while bounded
client-error `invalid_grant` retains its existing classification. OAuth
diagnostics omit raw bodies/URLs/opener/callback details. Overflowing
token expiry returns an infrastructure failure. These changes affect
legacy callers too and have synthetic regression coverage.

See [the reuse contract](crates/buzz-agent/DATABRICKS_REUSE.md) for API,
compatibility and caller obligations. Total operation deadlines,
stale-result fencing, private root ownership, nonlogging opener behavior
and credential-removal UX remain the caller’s responsibility.

### Related issue

Related discovery work: #6918. Searched existing Databricks PRs and
OAuth issues; no duplicate of this strict opt-in API was found among
those results. This is a new reuse boundary, not a claim of a live
credential leak.

### Testing

Published head: `cf33eb2f4f267d5808e068e35127d5504f0bc674`, based on
main `78618804ec86a014524ad7d1fb55928e8f5c3edf`.
Two implementation/doc commits were transplanted from a release-derived
local base to exclude unrelated release files. `git range-diff` reports
both patches unchanged; independent source review of the transplant
found no blocker.

**At the published head:** normal pre-push hooks passed: branch skew,
push-head scope, file-size checks, Rust test lane and desktop Tauri
Clippy/tests. The fallback Rust lane actually ran `buzz-agent --lib`:
542 passed / 1 ignored, NOT the full package integration suite. Hosted
full package/repository CI remains pending. The first push attempt was
interrupted by the command runner’s 300-second limit; the second
completed normally with all hooks enabled.

**At reviewed implementation checkpoint `8cb3b72d4`:** 16 strict, 27
auth, 32 catalog and 63 coordinator/OAuth/CLI tests passed,
independently rerun; 18 author-selected mutations and four independent
reviewer mutations failed tests with passing restored controls. The
subsequent `539319411` delta changed only two doc-comment blocks. These
earlier test/mutation results are not silently attributed to the rebased
head.

Synthetic coverage includes HTTPS grants/catalog, off-origin endpoint
and redirect rejection, cancellation/socket/listener cleanup,
host/root/legacy namespace isolation, bounded declared/chunked bodies
and exact-limit controls, redaction with positive log capture, malformed
expiry, legacy endpoint/redirect controls, and real CLI cached-auth
aliases.

Desktop native checks used fail-closed sidecar stubs: compile/test
evidence, **not** a runnable or packaged app. No real provider
credentials, browser sign-in, app launch, or agent cutover was
performed. Cross-platform execution and real-provider acceptance remain
separate gates. No merge or downstream adoption is requested by this PR.

---------

Signed-off-by: Brain <1a02c72794dcd0f07058a353bc3a81f4028b8c77c92c87fce6d5c8b85970a20b@buzz.block.builderlab.xyz>
Co-authored-by: Brain <1a02c72794dcd0f07058a353bc3a81f4028b8c77c92c87fce6d5c8b85970a20b@buzz.block.builderlab.xyz>
2026-09-13 08:04:56 -06:00

4.3 KiB
Raw Permalink Blame History

Opt-in Databricks connection reuse

databricks::DatabricksConnection reuses the PKCE coordinator and v2 catalog without running an agent, ACP, a CLI subprocess or any runtime configuration.

  • Construct with an explicit HTTPS workspace origin, an absolute app-owned cache root and a BrowserOpener. No host default or environment credential lookup. Construction can read/create that cache, but never networks or opens a browser.
  • connect() is user-initiated authentication only; it does not fetch models.
  • discover_models(filter) is always headless, including one 401-driven refresh. It never selects a model. Existing filtering, partial-success and labelled authenticated-empty/no-filter fallback remain; a vector is not proof of a complete catalog.
  • Strict discovery validates both OAuth endpoints from the very response used for refresh/code exchange. They must be same-origin HTTPS with no userinfo, query or fragment. Native discovery/token/catalog redirects are disabled. Browser SSO navigation is separate from the native client's redirect policy.
  • The caller chooses and exclusively owns its cache root BEFORE construction. databricks-strict separates strict state from legacy databricks caches and single-flight coordination even if roots coincide. It is not credential migration. Existing host/client/scopes hash and Unix owner-only atomic token persistence remain. Non-Unix token persistence remains disabled.
  • Keep secrets native. The supplied opener must not log authorization URLs or its failure details. Drop the operation future to cancel actual requests and the callback listener. Set an app-level overall deadline, generation-fence results, and never await under the agent-controller lock. A synchronous opener must return promptly; the library cannot cancel a blocking caller callback.
  • A cache root is an application trust boundary, not protection against a malicious process with the same OS user or a caller lending out that root.

Legacy compatibility and intentional shared changes

Existing public OAuth config/constructors, auth intents, cache defaults, static bearer selection, CLI auth, desktop discovery and v1/v2 catalog APIs remain. They DO NOT inherit strict same-origin or no-redirect policy.

Shared OAuth response handling has three intentional observable differences:

  1. Discovery and successful token responses are stream-capped at 1 MiB; OAuth error responses at 16 KiB. Exact-boundary JSON succeeds; oversized, malformed or unreadable responses are infrastructure failures, never grant rejection. Only a client-error error: invalid_grant within the bound retains refresh/code rejection classification. Non-success discovery bodies are not consumed. Existing catalog limits/retries are unchanged.
  2. OAuth logs no longer include raw response bodies, transport/decode details, callback error text or opener error text. Status/category logs remain. The legacy default opener still prints its manual sign-in URL deliberately; the strict API never selects that opener automatically. Strict catalog errors project fixed auth/infrastructure messages; legacy catalog diagnostics remain.
  3. A token response whose expires_in overflows epoch arithmetic now fails as an infrastructure error instead of panicking/wrapping.

No old cache migration/deletion, credential rewrite, app launch, internal host, internal release settings, or production dependency on a developer checkout is part of this patch.

Validation boundaries

Synthetic HTTPS servers use ephemeral test-only certificates; all cache contents, refresh tokens and callback codes are fabricated. Tests cover new and legacy paths, positive destination controls, refresh/code exchange, redirects, response limits, classifications, captured diagnostics, cancellation/retry, cache roots and namespace isolation. A real CLI child tests legacy auth aliases/cache reuse; existing coordinator tests include real subprocess single-flight/locking.

Before integration, require independent compatibility review at an exact commit, full buzz-agent package-suite evidence, affected desktop checks and repository gates. Focused tests are not a substitute. App orchestration, internal build-input wiring, credential-removal UX, native preview acceptance and real sign-in are separate subsequent work, not claims made by this helper patch.