Repository navigation
feat(github): add bounded evidence transport and rate limits - #2633
Conversation
|
No actionable comments were generated in the recent review.
|
| Layer / File(s) | Summary |
|---|---|
Rate-limit classification and connection state powershell/internal/services/github/Get-MtGitHubErrorStatusCode.ps1, powershell/internal/services/github/Get-MtGitHubRateLimit.ps1, powershell/internal/services/github/Get-MtGitHubRateLimitMessage.ps1, powershell/internal/services/github/Invoke-MtGitHubRateLimitGuard.ps1, powershell/internal/session/Clear-ModuleVariable.ps1, powershell/public/connect/Connect-MtGitHub.ps1, powershell/public/connect/Disconnect-MtGitHub.ps1, powershell/tests/functions/GitHubRateLimit.Tests.ps1 |
Rate-limit classification returns primary and secondary limit records. The guard tracks limits by connection, authority, and scope. Connection probes use the guard, and disconnect clears rate-limit state. Tests cover scopes, cooldowns, pagination, and connection probes. |
REST metadata and pagination powershell/internal/services/github/Invoke-MtGitHubRequest.ps1, powershell/tests/functions/Invoke-MtGitHubRequest.Tests.ps1, powershell/tests/functions/GitHubTransportTimeout.Tests.ps1 |
REST requests add metadata, per-call API-version overrides, pagination validation, partial-result evidence, and 30-second timeouts. Tests cover pagination, cache behavior, and stalled REST and GraphQL requests. |
Repository inventory validation powershell/internal/services/github/Get-MtGitHubRepositoryInventory.ps1, powershell/tests/functions/Get-MtGitHubRepositoryInventory.Tests.ps1 |
The inventory function validates collection completeness and repository identities, reports issues, and excludes conflicting identities. Tests cover duplicate and conflicting records, invalid evidence, and empty inventories. |
GraphQL read requests powershell/internal/services/github/Invoke-MtGitHubGraphQLRequest.ps1, powershell/tests/functions/Invoke-MtGitHubGraphQLRequest.Tests.ps1, powershell/tests/general/GraphCacheUsage.Tests.ps1 |
The GraphQL request function validates read queries and responses, applies rate-limit checks and timeouts, and caches eligible results. Tests cover request construction, cache behavior, errors, and connection changes. |
Affected-object cache extraction powershell/internal/report/affected-objects/Get-MtAffectedObjectFromCache.ps1, powershell/tests/functions/GitHubAffectedObjects.Tests.ps1 |
Affected-object extraction accepts specified legacy and metadata REST cache keys and rejects malformed or unrelated keys. Tests cover extraction and deduplication. |
Estimated code review effort: 4 (Complex) | ~60 minutes
Change: Feature
Sequence Diagram(s)
sequenceDiagram
participant Invoke-MtGitHubRequest
participant Invoke-MtGitHubRateLimitGuard
participant GitHubRESTAPI
participant SessionCache
Invoke-MtGitHubRequest->>Invoke-MtGitHubRateLimitGuard: Check quota before request
Invoke-MtGitHubRateLimitGuard-->>Invoke-MtGitHubRequest: Allow or block request
Invoke-MtGitHubRequest->>GitHubRESTAPI: Send bounded request
GitHubRESTAPI-->>Invoke-MtGitHubRequest: Return response and headers
Invoke-MtGitHubRequest->>Invoke-MtGitHubRateLimitGuard: Record response quota
Invoke-MtGitHubRequest->>SessionCache: Cache complete, integrity-valid result
Possibly related issues
- maester365/maester#2524 — The PR tests clearing GraphQL cache evidence on disconnect and reconnect, which relates to stale cached data after a tenant change.
Possibly related PRs
- maester365/maester#2635 — This PR consumes the REST and GraphQL transports, inventory results, pagination, and rate-limit handling added here.
- maester365/maester#2525 — This PR consumes the repository inventory, REST pagination, GraphQL reads, and rate-limit handling provided here.
- maester365/maester#2646 — This PR renders and navigates affected-object records whose GitHub extraction changes are included here.
Suggested labels: enhancement, status: needs review
Suggested reviewers: merill
Merge Risk: 
Minimal · up to 4ba54
-
This change adds bounded GitHub REST and GraphQL transport with shared rate-limit handling and repository inventory validation. No actionable merge-blocking risk remains in the reviewed changes. Maintainer review and approval are still required.
Pre-merge checks: 
5
-
Full details: Description check
-
Explanation
The description is detailed and covers the implementation scope, validation results, dependencies, limitations, and testing status. It does not include the template's issue-closing entry or checkbox format, but the required technical information is mostly complete.
Full details: Docstring Coverage
-
Explanation
No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (7 skipped: 7 unsupported.)
-
Finishing Touches
-
Generate unit tests (beta)
-
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
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.
Up to standards ✅🟢 Issues
|
There was a problem hiding this comment.
🟡 Changes recommended
Rate-limit handling conflates API-specific primary resets with shared secondary cooldowns, potentially blocking other APIs unnecessarily or allowing requests before the secondary cooldown expires.
1 open issue
What changed in this PR
This PR adds shared GitHub evidence transport for Maester, independently of the deletion assessments that will consume it.
Changes:
- Adds opt-in REST evidence metadata, bounded pagination, and a separately cached read-only GraphQL transport.
- Introduces connection-scoped rate-limit protection and request timeouts.
- Adds repository identity validation, REST cache-key recognition for affected objects, and focused regression tests.
| File | Description |
|---|---|
powershell/tests/general/GraphCacheUsage.Tests.ps1 |
Allows the GraphQL transport cache switch. |
powershell/tests/functions/Invoke-MtGitHubRequest.Tests.ps1 |
Tests REST metadata, pagination, caching, and timeouts. |
powershell/tests/functions/Invoke-MtGitHubGraphQLRequest.Tests.ps1 |
Tests GraphQL requests, errors, and cache isolation. |
powershell/tests/functions/GitHubTransportTimeout.Tests.ps1 |
Adds loopback fixtures for stalled responses. |
powershell/tests/functions/GitHubRateLimit.Tests.ps1 |
Tests cooldowns, quota separation, and bootstrap limits. |
powershell/tests/functions/GitHubAffectedObjects.Tests.ps1 |
Tests supported REST cache-key recognition. |
powershell/tests/functions/Get-MtGitHubRepositoryInventory.Tests.ps1 |
Tests repository identity validation and conflicts. |
powershell/public/connect/Disconnect-MtGitHub.ps1 |
Clears connection rate-limit state. |
powershell/public/connect/Connect-MtGitHub.ps1 |
Applies shared rate-limit protection to connection probes. |
powershell/internal/session/Clear-ModuleVariable.ps1 |
Documents cooldown preservation across cache resets. |
powershell/internal/services/github/Invoke-MtGitHubRequest.ps1 |
Adds REST evidence metadata, pagination bounds, and timeouts. |
powershell/internal/services/github/Invoke-MtGitHubRateLimitGuard.ps1 |
Records and enforces connection-scoped cooldowns. |
powershell/internal/services/github/Invoke-MtGitHubGraphQLRequest.ps1 |
Adds cached read-only GraphQL transport. |
powershell/internal/services/github/Get-MtGitHubRepositoryInventory.ps1 |
Collects repositories and validates their identities. |
powershell/internal/services/github/Get-MtGitHubRateLimitMessage.ps1 |
Delegates diagnostics to shared limit classification. |
powershell/internal/services/github/Get-MtGitHubRateLimit.ps1 |
Classifies limits and calculates cooldown deadlines. |
powershell/internal/services/github/Get-MtGitHubErrorStatusCode.ps1 |
Reads status from structured rate-limit errors. |
powershell/internal/report/affected-objects/Get-MtAffectedObjectFromCache.ps1 |
Recognizes REST metadata keys and excludes GraphQL keys. |
Review effort: Balanced
merill
left a comment
There was a problem hiding this comment.
Thanks @thetechgy, looks good to me. A couple of optional things if you get a chance: a line in the description saying the GraphQL helper has no caller until #2635, and the nested Invoke-ConnectionProbe in Connect-MtGitHub could move into its own internal helper.

Description
This separates the shared GitHub evidence handling from #2525 so it can be reviewed independently of the deletion assessments.
The changes cover the following:
Evidence remains a session snapshot until a new run, reconnect/disconnect or module reset clears it. Standalone
Invoke-MtTestcalls reuse that snapshot. The GraphQL transport is added to the existing cache-switch allowlist; checks do not bypass the cache.Validation
On Linux / PowerShell 7.6.6 / Pester 5.7.1, the full unit-test command completed with 5 failures out of 6,691 tests. All five reproduced on the unchanged PR head
9e921e48b2274799d004fac5c8ef691220f3794e: one console-colour assertion and four Azure request URI assertions. All 79 console tests passed in a separate run with process-local colour settings normalized. These baseline failures were not changed in this PR.The GitHub transport tests, including real loopback header/body timeout fixtures, passed in the full run. All 34 focused rate-limit tests passed, including 12 combined-limit cases covering REST HTTP errors, GraphQL HTTP errors and HTTP 200 GraphQL errors. The new combined-limit cases failed before the fix. Changed-file PSScriptAnalyzer, module build and output validation passed. Read-only reports from a combined build exercised normal REST and GraphQL collection against a live EMU organization. The reports do not contain a source revision, so they do not establish exact-revision validation of this PR. Live timeout, rate-limit and GHE.com behavior remains unverified; those failure paths are covered by the fixtures. No tenant resources were changed.
Dependencies
This PR is independent of the setting fixes in #2525 and reporting in #2634. Those three may merge independently; merging #2525 first is recommended. #2635 requires both this PR and reporting to merge first.
PR #2540 has reconciled this transport and the other foundations at
e70990fab7c2a2dad034b9840502d89d59d7eab5. After the prerequisites merge, reconcile the dependent branches against actual upstream main and repeat affected validation.Current revision:
4ba540611848b749b93cd547173eb4dd2f1a4ff6. Hosted validation is running for this revision. Maintainer review and approval remain required.Summary by CodeRabbit