Skip to content

fix(drive): harden export and push failure recovery - #2279

Merged
fangshuyu-768 merged 8 commits into
mainfrom
fix/drive-export-error-recovery
Aug 11, 2026
Merged

fix(drive): harden export and push failure recovery#2279
fangshuyu-768 merged 8 commits into
mainfrom
fix/drive-export-error-recovery

Conversation

@fangshuyu-768

@fangshuyu-768 fangshuyu-768 commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

Summary

Harden Drive export and push failure recovery for the error patterns observed in production.

Changes

Export recovery

  • Disambiguate code 9499 only at the Drive export task boundary using its exact throttling message, leaving the shared classifier unchanged and preserving invalid_parameters everywhere else.
  • Add typed mappings for export codes 1069902, 1069906, 1069914, and 1069918.
  • Stop export polling immediately on the 9499 rate-limit variant and return ticket-aware resume guidance instead of amplifying throttling.
  • Add actionable recovery hints for permission, deleted document, invalid token/type, and extension/sub-ID failures.

Push failure handling

  • Keep upload size mismatch (1062009) file-local so independent files continue, while stopping the batch on shared failures such as resource contention, quota exhaustion, multipart internal errors, and HTTP/network failures.
  • Add bounded-backoff guidance for retryable push failures without inventing a retry delay that the upstream response did not provide.
  • Register Drive multipart error 1663 as a retryable server error.
  • Document finite retry behavior and the expanded push failure contract.

Tests and docs

  • Add command-level regression coverage for export task creation/polling and permanent export failures.
  • Add push coverage for size mismatch, HTTP 502, resource contention, quota exhaustion, and Drive code 1663.
  • Update the Drive export and push skill references.

Test Plan

  • go test -race -count=1 ./internal/errclass ./shortcuts/drive
  • make vet
  • make fmt-check
  • node scripts/skill-format-check/index.js
  • go test -C lint ./... -count=1
  • go run -C lint . --changed-from origin/main ..
  • make quality-gate
  • Command-level HTTP stubs verify export and push API/error boundaries.

make unit-test passed all changed and Drive-related packages under -race. The aggregate run encountered the repository's unrelated macOS TempDir RemoveAll flake in internal/qualitygate/rules (.git: directory not empty); the failing package passed when rerun in isolation. Live rate-limit and destructive push E2E cases were not forced because they would be unsafe or nondeterministic; deterministic command-level HTTP stubs cover the changed behavior.

Related Issues

  • None

Summary by CodeRabbit

  • Bug Fixes

    • Improved Google Drive export error handling and recovery guidance for permissions, deleted files, invalid references, and unsupported formats.
    • Correctly distinguishes rate limits from other errors and applies safer retry behavior.
    • Drive push operations now provide clearer failure classifications, quota handling, and retry guidance.
    • Pull and sync operations continue processing remaining files when an individual download is unavailable.
  • Documentation

    • Updated Drive export and push guidance with backoff, retry timing, and failure-handling instructions.

@github-actions github-actions Bot added domain/ccm PR touches the ccm domain size/M Single-domain feat or fix with limited business impact labels Aug 11, 2026
@coderabbitai

coderabbitai Bot commented Aug 11, 2026

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Drive error metadata now covers multipart, quota, and export failures. Export handling distinguishes rate-limited 9499 responses from other parameter errors. Push handling adds terminal classifications, retry metadata, and recovery hints. Pull and sync continue after individual download failures.

Changes

Drive error handling

Layer / File(s) Summary
Drive error classification
internal/errclass/codemeta_drive.go, internal/errclass/codemeta_drive_test.go, internal/errclass/codemeta_test.go, shortcuts/drive/drive_errors.go
Drive multipart-upload, quota, and export codes now map to typed classifications. Code 9499 is treated as a rate limit only when its message indicates too many requests.
Export creation and polling recovery
shortcuts/drive/drive_export_common.go, shortcuts/drive/drive_errors.go, shortcuts/drive/drive_export_test.go, shortcuts/sheets/lark_sheet_workbook_export_test.go, skills/lark-drive/references/lark-drive-export.md
Export creation and polling normalize overloaded 9499 errors. Permanent export failures receive command-specific hints. Tests cover retry behavior, polling termination, ticket continuation, and workbook export propagation.
Push failure classification and retry metadata
shortcuts/drive/drive_push.go, shortcuts/drive/drive_push_test.go, skills/lark-drive/references/lark-drive-push.md
Push handling distinguishes size mismatches, quotas, conflicts, server errors, transport failures, and local file changes. Retryable upload failures expose retry guidance and delay requirements.
Pull and sync continuation
shortcuts/drive/drive_pull_test.go, shortcuts/drive/drive_sync_test.go
Pull and sync report partial failures after HTTP 404 responses and continue downloading subsequent files.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DriveAPI
  participant createDriveExportTask
  participant withDriveExportCreateRecovery
  participant WorkbookExport
  DriveAPI->>createDriveExportTask: return code 9499 with too many requests
  createDriveExportTask->>withDriveExportCreateRecovery: normalize and classify response
  withDriveExportCreateRecovery-->>createDriveExportTask: return retryable rate-limit error
  createDriveExportTask-->>WorkbookExport: preserve typed error and caller recovery hint
Loading

Possibly related PRs

Suggested labels: bugfix

Suggested reviewers: liangshuo-1

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 27.59% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely summarizes the main changes to Drive export and push failure recovery.
Description check ✅ Passed The description includes all required sections and clearly documents the scope, changes, tests, known flake, and related issues.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/drive-export-error-recovery

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@fangshuyu-768
fangshuyu-768 force-pushed the fix/drive-export-error-recovery branch from 48c787a to a7083ce Compare August 11, 2026 03:06
@github-actions

github-actions Bot commented Aug 11, 2026

Copy link
Copy Markdown

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@29087fddabd8d1eb098b28ec132e7701d8d49c4c

🧩 Skill update

npx skills add larksuite/cli#fix/drive-export-error-recovery -y -g

@codecov

codecov Bot commented Aug 11, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 86.95652% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.45%. Comparing base (d289566) to head (29087fd).

Files with missing lines Patch % Lines
shortcuts/drive/drive_push.go 78.12% 6 Missing and 1 partial ⚠️
shortcuts/drive/drive_errors.go 94.44% 1 Missing and 1 partial ⚠️
Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2279   +/-   ##
=======================================
  Coverage   76.44%   76.45%           
=======================================
  Files        1013     1013           
  Lines      111972   112034   +62     
=======================================
+ Hits        85601    85658   +57     
- Misses      19860    19864    +4     
- Partials     6511     6512    +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@fangshuyu-768
fangshuyu-768 force-pushed the fix/drive-export-error-recovery branch from a7083ce to 91b9925 Compare August 11, 2026 03:19
@fangshuyu-768 fangshuyu-768 changed the title fix(drive): improve export error recovery fix(drive): harden export and push failure recovery Aug 11, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/drive/drive_push.go`:
- Around line 611-613: Update the retry-delay conversion in the errs.RetryAfter
handling so fractional durations are rounded up to the next whole second before
assigning decision.RetryAfterSeconds, including saturated durations.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 155f1d4f-12c0-457c-bba9-c01d5a1edc69

📥 Commits

Reviewing files that changed from the base of the PR and between a7083ce and 54c001d.

📒 Files selected for processing (5)
  • internal/errclass/codemeta_drive.go
  • internal/errclass/codemeta_test.go
  • shortcuts/drive/drive_push.go
  • shortcuts/drive/drive_push_test.go
  • skills/lark-drive/references/lark-drive-push.md

Comment thread shortcuts/drive/drive_push.go Outdated
@fangshuyu-768
fangshuyu-768 force-pushed the fix/drive-export-error-recovery branch from 54c001d to 2e6d725 Compare August 11, 2026 03:59
Comment thread shortcuts/drive/drive_push.go Outdated
wittam-01
wittam-01 previously approved these changes Aug 11, 2026
Comment thread shortcuts/drive/drive_errors.go

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/drive/drive_pull_test.go`:
- Around line 1139-1152: Update the failed-item assertions in
shortcuts/drive/drive_pull_test.go:1139-1152 and
shortcuts/drive/drive_sync_test.go:427-441. In the pull test, assert the first
item reports action "failed", download phase, HTTP 404, and retryable false; in
the sync test, assert the first driveSyncItem exposes the same failed-download
metadata. Keep the existing continuation and successful b.txt assertions.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 348cd70d-7e87-4238-b6e3-a7aab49e206c

📥 Commits

Reviewing files that changed from the base of the PR and between 54c001d and 11b13c6.

📒 Files selected for processing (4)
  • shortcuts/drive/drive_pull_test.go
  • shortcuts/drive/drive_push.go
  • shortcuts/drive/drive_push_test.go
  • shortcuts/drive/drive_sync_test.go
🚧 Files skipped from review as they are similar to previous changes (1)
  • shortcuts/drive/drive_push.go

Comment thread shortcuts/drive/drive_pull_test.go
Comment thread shortcuts/drive/drive_push.go

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/sheets/lark_sheet_workbook_export_test.go`:
- Around line 121-126: Extend the error assertions around errs.ProblemOf(err) to
require problem.Category == errs.CategoryAPI. Use errors.As to extract the
wrapped *errs.APIError, then verify its preserved cause with errors.Is or
Unwrap() against the expected underlying error while retaining the existing
subtype, code, and retryable checks.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 119acede-3980-4b58-a5ad-c633925761c8

📥 Commits

Reviewing files that changed from the base of the PR and between 11b13c6 and 53c77ab.

📒 Files selected for processing (9)
  • internal/errclass/codemeta_drive.go
  • internal/errclass/codemeta_test.go
  • shortcuts/drive/drive_errors.go
  • shortcuts/drive/drive_export_test.go
  • shortcuts/drive/drive_pull_test.go
  • shortcuts/drive/drive_push_test.go
  • shortcuts/drive/drive_sync_test.go
  • shortcuts/sheets/lark_sheet_workbook_export_test.go
  • skills/lark-drive/references/lark-drive-push.md
🚧 Files skipped from review as they are similar to previous changes (8)
  • shortcuts/drive/drive_pull_test.go
  • shortcuts/drive/drive_sync_test.go
  • internal/errclass/codemeta_drive.go
  • internal/errclass/codemeta_test.go
  • skills/lark-drive/references/lark-drive-push.md
  • shortcuts/drive/drive_export_test.go
  • shortcuts/drive/drive_push_test.go
  • shortcuts/drive/drive_errors.go

Comment thread shortcuts/sheets/lark_sheet_workbook_export_test.go Outdated
@fangshuyu-768
fangshuyu-768 merged commit 82e628b into main Aug 11, 2026
41 checks passed
@fangshuyu-768
fangshuyu-768 deleted the fix/drive-export-error-recovery branch August 11, 2026 06:20
@liangshuo-1 liangshuo-1 mentioned this pull request Aug 11, 2026
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

domain/ccm PR touches the ccm domain size/M Single-domain feat or fix with limited business impact

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants