mirror of
https://github.com/larksuite/cli.git
synced 2026-07-06 16:18:05 +08:00
98173ae5a9
Drive-domain errors now leave the CLI as typed, machine-branchable envelopes — a stable `type` plus `subtype` and named fields (param, params, retryable, log_id, hint) — so scripts and AI agents can branch on structure and act on a recovery hint instead of parsing prose. Changes: - Every error produced in the drive domain — validation, file I/O, and the failures returned from its Lark API calls — is emitted as a typed errs.* error; the exit code is derived from the error category. Drive's API calls now go through a shared typed classifier, so failures carry subtype, troubleshooter, a recovery hint, and the request's log_id whether the server returns it in the response body or the x-tt-logid header; an already-typed network/auth error is never downgraded into a generic API error. - Known API conditions (resource conflict, cross-tenant, cross-brand, ...) carry a recovery hint keyed by their error class; a command can refine that hint with command-specific guidance. - Batch partial failures (+push / +pull / +sync, where some items succeed and some fail) now report an honest ok:false multi-status result on stdout — the summary and every per-item outcome stay machine-readable — and exit non-zero, instead of a misleading ok:true success envelope. - Duplicate rel_path conflicts report each colliding path as a structured params entry (RFC 7807 invalid-params style). - Static guards lock the drive path so legacy error construction — direct envelopes or the auto-classifying API helpers — cannot be reintroduced, making drive the template for the remaining domains. Output changes worth noting for consumers: - Error envelopes now carry typed type/subtype and named fields; exit codes follow the error category (malformed or incomplete API responses are reported as internal errors rather than generic API errors). - Batch partial failures (+push / +pull / +sync) emit an ok:false result envelope on stdout (summary + per-item items[]) and exit non-zero; the per-item results stay on stdout rather than in a stderr error envelope. Errors surfaced through shared cross-domain helpers (scope precheck, media import upload, metadata lookup, save-path resolution) are not yet typed; they migrate with the shared layer in a follow-up change.
90 lines
3.2 KiB
Go
90 lines
3.2 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package drive
|
|
|
|
import (
|
|
"errors"
|
|
"strings"
|
|
|
|
"github.com/larksuite/cli/errs"
|
|
"github.com/larksuite/cli/extension/fileio"
|
|
"github.com/larksuite/cli/internal/output"
|
|
)
|
|
|
|
// wrapDriveNetworkErr returns err unchanged when it is already a typed errs.*
|
|
// error (preserving its subtype / code / log_id from the runtime boundary),
|
|
// and only wraps a raw, unclassified error as a transport-level network error.
|
|
func wrapDriveNetworkErr(err error, format string, args ...any) error {
|
|
if _, ok := errs.ProblemOf(err); ok {
|
|
return err
|
|
}
|
|
return errs.NewNetworkError(errs.SubtypeNetworkTransport, format, args...).WithCause(err)
|
|
}
|
|
|
|
// driveInputStatError maps a FileIO.Stat/Open error for input file validation
|
|
// to a typed validation error:
|
|
// - Path validation failures → "unsafe file path: ..."
|
|
// - Other errors → "cannot read file: ..."
|
|
func driveInputStatError(err error) error {
|
|
if err == nil {
|
|
return nil
|
|
}
|
|
if errors.Is(err, fileio.ErrPathValidation) {
|
|
return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe file path: %s", err).WithCause(err)
|
|
}
|
|
return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot read file: %s", err).WithCause(err)
|
|
}
|
|
|
|
// driveSaveError maps a FileIO.Save error to a typed error. Path validation
|
|
// failures are validation errors (exit code 2); mkdir / write failures are
|
|
// internal file-I/O errors (exit code 5).
|
|
func driveSaveError(err error) error {
|
|
if err == nil {
|
|
return nil
|
|
}
|
|
var me *fileio.MkdirError
|
|
switch {
|
|
case errors.Is(err, fileio.ErrPathValidation):
|
|
return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithCause(err)
|
|
case errors.As(err, &me):
|
|
return errs.NewInternalError(errs.SubtypeFileIO, "cannot create parent directory: %s", err).WithCause(err)
|
|
default:
|
|
return errs.NewInternalError(errs.SubtypeFileIO, "cannot create file: %s", err).WithCause(err)
|
|
}
|
|
}
|
|
|
|
// appendDriveExportRecoveryHint attaches a recovery hint to err while preserving
|
|
// its original classification (typed subtype/code or legacy detail), only falling
|
|
// back to a typed internal error when err is unclassified.
|
|
func appendDriveExportRecoveryHint(err error, hint string) error {
|
|
if err == nil {
|
|
return nil
|
|
}
|
|
// An already-typed error keeps its own category/subtype/code/log_id
|
|
// (per ERROR_CONTRACT.md "propagate typed errors unchanged"); we only
|
|
// append the recovery hint. p points at the embedded Problem, so the
|
|
// mutation is reflected in the returned err.
|
|
if p, ok := errs.ProblemOf(err); ok {
|
|
if strings.TrimSpace(p.Hint) != "" {
|
|
p.Hint = p.Hint + "\n" + hint
|
|
} else {
|
|
p.Hint = hint
|
|
}
|
|
return err
|
|
}
|
|
// Legacy *output.ExitError fallback: preserve the original error's
|
|
// class/exit code by appending the hint in place rather than downgrading
|
|
// to api/server_error.
|
|
var exitErr *output.ExitError
|
|
if errors.As(err, &exitErr) && exitErr.Detail != nil {
|
|
if strings.TrimSpace(exitErr.Detail.Hint) != "" {
|
|
exitErr.Detail.Hint = exitErr.Detail.Hint + "\n" + hint
|
|
} else {
|
|
exitErr.Detail.Hint = hint
|
|
}
|
|
return err
|
|
}
|
|
return errs.NewInternalError(errs.SubtypeSDKError, "%s", err.Error()).WithHint(hint).WithCause(err)
|
|
}
|