fix(api): support service-hosted Discovery documents

[goutamadwant]

Closes #1048

What Problem This Solves

Fixes an issue where gog api describe and gog api call returned a central Discovery Directory 404 for APIs such as Meet v2 whose Discovery document is published only on the service host.

Why This Change Was Made

The Discovery client now retries a default-directory 404 against the safely constructed {api}.googleapis.com/$discovery/rest?version={version} URL. Explicit GOG_DISCOVERY_BASE_URL overrides, non-404 responses, and unsafe service names do not trigger fallback. Existing OAuth request and redirect host validation remains unchanged.

User Impact

Generic API commands can resolve service-hosted Discovery documents, including Meet v2 resources not exposed by first-class commands, without brittle environment-variable URL fragments.

Evidence

• go test ./internal/discoveryapi ./internal/cmd
• make ci
• go run ./cmd/gog api describe meet v2 meet.conferenceRecords.list
• go run ./cmd/gog --dry-run api call meet v2 meet.conferenceRecords.list --params '{"pageSize":1}'

The regression test fails on current main at the central Directory 404 and passes after the fallback. The credential-free live command resolves the official Meet v2 Discovery document, and the dry run builds https://meet.googleapis.com/v2/conferenceRecords?pageSize=1.

Captured after-fix terminal output (no account or credentials used):

$ go run ./cmd/gog api describe meet v2 meet.conferenceRecords.list | jq '{id, resource, name, http_method: .spec.httpMethod, path: .spec.path}'
{
  "id": "meet.conferenceRecords.list",
  "resource": "conferenceRecords",
  "name": "list",
  "http_method": "GET",
  "path": "v2/conferenceRecords"
}

$ go run ./cmd/gog --dry-run api call meet v2 meet.conferenceRecords.list --params '{"pageSize":1}'
Dry run: would api.call
{
  "api": "meet",
  "has_body": false,
  "http_method": "GET",
  "method": "meet.conferenceRecords.list",
  "url": "https://meet.googleapis.com/v2/conferenceRecords?pageSize=1",
  "version": "v2"
}

Limitations

The fallback only runs after a 404 from the implicit default central Directory. It does not apply to explicit Discovery base overrides, non-404 responses, or service names that are not safe DNS labels. No authenticated Meet API request was made.

Disclosure: AI was used to understand the codebase and review the fix.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 31, 2026, 5:04 AM ET / 09:04 UTC.

ClawSweeper review

What this changes

The PR retries a central Google Discovery Directory 404 at a safely derived service-hosted document URL and adds fallback-boundary tests.

Merge readiness

✅ Ready for maintainer review

This clean, proof-positive PR should remain open for normal maintainer merge review; the linked Discovery retrieval bug is not fixed on current main yet.

Priority: P2
Reviewed head: 45049ab0efc1b2ce526d50d0cf80abdf2fa5d771

Review scores

Measure	Result	What it means
Overall readiness	🦞 diamond lobster (5/6)	The focused implementation has direct command-level proof, independent maintainer reproduction, and coverage of its fallback boundaries.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (terminal): The changed owner is Discovery document retrieval; credential-free after-fix terminal traces exercise api describe against Meet v2 and the dry-run request-construction path, while an independent collaborator confirmed the same result at the exact head.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The changed owner is Discovery document retrieval; credential-free after-fix terminal traces exercise api describe against Meet v2 and the dry-run request-construction path, while an independent collaborator confirmed the same result at the exact head.
Evidence reviewed	5 items	Introduced fallback boundary: The PR retries only an implicit default-base 404, derives an HTTPS googleapis.com host from a DNS-label-safe service name, and preserves explicit override and non-404 behavior. Focused boundary coverage: Tests cover successful Meet v2 fallback plus exclusion for custom bases, non-404 responses, and unsafe service names. Existing authenticated-call boundary: The command resolves the Discovery document before building a request, then retains existing Google-host validation before an authenticated API request proceeds.
Findings	None	None.
Security	None	None.

How this fits together

Generic gog api commands fetch a Google Discovery document, resolve a method, and build a Google API request. This change affects document retrieval when the central Directory lacks a service-hosted API document.

flowchart LR
  A[Generic API command] --> B[Discovery document client]
  B --> C[Central Discovery Directory]
  C --> D{Document found?}
  D -->|Yes| E[Resolve API method]
  D -->|Default-directory 404| F[Service-hosted document]
  F --> E
  E --> G[Build API request]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Patch scope	176 added, 1 removed across 2 files	The production change is confined to Discovery retrieval and is accompanied by focused coverage.
Production vs test lines	production +44/-1, tests +132/-0	Most added code is boundary coverage for the new fallback.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #1048
Summary: This PR is the candidate fix for the linked, still-open Discovery retrieval bug.

Members:

• canonical: api describe/call cannot use service-hosted Discovery documents such as Meet v2 #1048 - Both items identify the same central-directory 404 for Meet v2 and the service-hosted document fallback.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Technical review

Best possible solution:

Merge the narrow fallback with its boundary tests while retaining the existing target-URL validation for authenticated calls.

Do we have a high-confidence way to reproduce the issue?

Yes: the supplied credential-free terminal evidence and independent collaborator review reproduce the central Directory 404 on main and show success at this exact PR head.

Is this the best way to solve the issue?

Yes: limiting fallback to a default-directory 404 and a validated service-derived HTTPS host is a compatible, maintainable repair.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against be4037f7c8f6.

Labels

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P2: This repairs generic API access for a bounded class of service-hosted Google Discovery documents.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The changed owner is Discovery document retrieval; credential-free after-fix terminal traces exercise api describe against Meet v2 and the dry-run request-construction path, while an independent collaborator confirmed the same result at the exact head.
• proof: sufficient: Contributor real behavior proof is sufficient. The changed owner is Discovery document retrieval; credential-free after-fix terminal traces exercise api describe against Meet v2 and the dry-run request-construction path, while an independent collaborator confirmed the same result at the exact head.

Evidence

What I checked:

• Introduced fallback boundary: The PR retries only an implicit default-base 404, derives an HTTPS googleapis.com host from a DNS-label-safe service name, and preserves explicit override and non-404 behavior. (internal/discoveryapi/discovery.go:91, 45049ab0efc1)
• Focused boundary coverage: Tests cover successful Meet v2 fallback plus exclusion for custom bases, non-404 responses, and unsafe service names. (internal/discoveryapi/discovery_test.go:20, 45049ab0efc1)
• Existing authenticated-call boundary: The command resolves the Discovery document before building a request, then retains existing Google-host validation before an authenticated API request proceeds. (internal/cmd/api.go:83, 45049ab0efc1)
• Real behavior proof: The PR body supplies credential-free after-fix terminal output for api describe and dry-run api call; a collaborator independently reproduced the main-branch 404 and confirmed the exact PR head resolves Meet v2 and builds the expected URL. (45049ab0efc1)
• Feature provenance: The original Discovery-backed command path, including the central-only description URL, was introduced with the Discovery API feature and is still present on current main before this PR. (internal/discoveryapi/discovery.go:86, 0122f09d84e5)

Likely related people:

• Peter Steinberger: Raw commit 0122f09 adds internal/discoveryapi/discovery.go:73 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 0122f09d84e5; files: internal/discoveryapi/discovery.go)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (2 earlier review cycles)

• reviewed 2026-08-30T19:43:07.203Z sha 45049ab :: needs real behavior proof before merge. :: none
• reviewed 2026-08-30T19:51:44.671Z sha 45049ab :: needs maintainer review before merge. :: none

[steipete]

LAND recommended for head 45049ab0efc1b2ce526d50d0cf80abdf2fa5d771. I reproduced the central Directory HTTP 404 with a binary built from current main, reviewed the fallback and explicit-base/error boundaries, then built this exact PR head and ran it against Google's public Discovery endpoint with an isolated temporary GOG_HOME and no credentials.

$ gog api describe meet v2 meet.conferenceRecords.list
{"id":"meet.conferenceRecords.list","method":"GET","path":"v2/conferenceRecords"}
exit 0
$ gog --dry-run api call meet v2 meet.conferenceRecords.list --params '{"pageSize":1}'
Dry run: would api.call
{"api":"meet","has_body":false,"http_method":"GET","method":"meet.conferenceRecords.list","url":"https://meet.googleapis.com/v2/conferenceRecords?pageSize=1","version":"v2"}
exit 0

The first JSON above projects the method ID, HTTP method, and path from the command output. go test ./internal/discoveryapi -count=1 passed, and Codex autoreview of the exact commit was scoped-clean at its default P0 threshold. Existing PR CI is green. No authenticated Meet request was made; this verifies the changed public-document retrieval boundary and request construction.

No code correction was needed. The maintainer landing should add the changelog entry thanking @goutamadwant and retain contributor credit.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: fix(api): support service-hosted Discovery documents This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.

[steipete]

Landed in e7dede7 with contributor credit, changelog thanks, and a README note. Full local make ci and CI on the updated head passed. The credential-free live proof resolves Meet v2 and builds the expected conference-records request. Thanks @goutamadwant!