mirror of
https://github.com/larksuite/cli.git
synced 2026-07-03 14:02:43 +08:00
fe72e41fb2
Introduce a typed error contract framework for lark-cli so in-process
Go callers can branch via errors.As(&errs.XxxError{}) and shell scripts,
AI agents, and protocol adapters can branch on stable JSON type/subtype
fields instead of regex-parsing free-form messages.
Adds:
- Canonical taxonomy under errs/ (9 categories + typed Error structs
embedding a shared Problem, RFC 7807-aligned)
- Centralized Lark code metadata + identity-aware BuildAPIError dispatch
- Typed JSON envelope writer alongside the legacy envelope writer
- MCP / OAuth (RFC 6750 Bearer) projection adapters
- Five CI lint guards preventing ad-hoc taxonomy drift
Backward compatibility: legacy *output.ExitError producers (ErrAPI,
ErrWithHint, Errorf, ErrBare) and business shortcuts that use them
continue to render the legacy envelope unchanged. SecurityPolicyError
wire format and exit code are preserved via a carve-out; taxonomy
migration is deferred to PR 2. Domain-specific business migration is
staged across PR 3+.
Framework-direct paths now return typed *errs.*Error: ErrAuth /
ErrValidation / ErrNetwork emit category literals on the wire
(authentication / validation / network), *core.ConfigError is promoted
at the cmd/root boundary with exit code aligned from 2 to 3, and Lark
API permission denials classified by BuildAPIError exit 3.
At the SDK boundary, WrapDoAPIError preserves any already-classified
error (legacy *output.ExitError or typed *errs.*) so output.ErrAuth
from missing credentials surfaces with the auth category and exit 3
intact instead of being downgraded to a network error. Policy responses
classified by BuildAPIError (codes 21000 / 21001) extract challenge_url
and the canonical hint from the response body, matching what the
auth transport already surfaces at the HTTP layer; non-https
challenge URLs are dropped.
First PR in the feat/error-contract-* series.
96 lines
3.3 KiB
Go
96 lines
3.3 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package client
|
|
|
|
import (
|
|
"bytes"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"io"
|
|
"strings"
|
|
|
|
"github.com/larksuite/cli/errs"
|
|
"github.com/larksuite/cli/internal/output"
|
|
)
|
|
|
|
const rawAPIJSONHint = "The endpoint may have returned an empty or non-standard JSON body. If it returns a file, rerun with --output."
|
|
|
|
// WrapDoAPIError upgrades malformed JSON decode errors from the SDK into
|
|
// actionable API errors for raw `lark-cli api` calls. All other failures
|
|
// remain network errors.
|
|
//
|
|
// Already-classified errors pass through unchanged: any *output.ExitError
|
|
// (legacy envelope from output.ErrAuth / output.ErrAPI / output.ErrWithHint)
|
|
// and any typed *errs.* error (carries an embedded Problem) keeps its own
|
|
// category and exit code. This is what makes the wrap idempotent on the
|
|
// auth/credential chain — resolveAccessToken returns output.ErrAuth for
|
|
// missing tokens, and that classification must survive the SDK boundary.
|
|
//
|
|
// Deprecated: legacy *output.ExitError wire shape (api_error + rawAPIJSONHint
|
|
// on JSON-decode, network otherwise) for the wrap-from-untyped branch.
|
|
// Preserved so SDK Do() callers keep the original envelope until per-domain
|
|
// migration to typed errors. New code should route through
|
|
// APIClient.CheckResponse (typed *errs.APIError) or construct
|
|
// *errs.NetworkError / *errs.InternalError directly.
|
|
func WrapDoAPIError(err error) error {
|
|
if err == nil {
|
|
return nil
|
|
}
|
|
var existing *output.ExitError
|
|
if errors.As(err, &existing) {
|
|
return err
|
|
}
|
|
if _, ok := errs.ProblemOf(err); ok {
|
|
return err
|
|
}
|
|
if isJSONDecodeError(err, false) {
|
|
return output.ErrWithHint(output.ExitAPI, "api_error",
|
|
fmt.Sprintf("API returned an invalid JSON response: %v", err), rawAPIJSONHint)
|
|
}
|
|
return output.ErrNetwork("API call failed: %v", err)
|
|
}
|
|
|
|
// WrapJSONResponseParseError upgrades empty or malformed JSON response bodies
|
|
// into API errors with hints instead of generic parse failures.
|
|
//
|
|
// Deprecated: legacy *output.ExitError wire shape (api_error + ExitAPI +
|
|
// rawAPIJSONHint). The 3-branch behaviour is preserved so existing callers
|
|
// of internal/client/response.go keep emitting the same envelope until
|
|
// per-domain migration to typed errors.
|
|
func WrapJSONResponseParseError(err error, body []byte) error {
|
|
if err == nil {
|
|
return nil
|
|
}
|
|
if len(bytes.TrimSpace(body)) == 0 {
|
|
return output.ErrWithHint(output.ExitAPI, "api_error",
|
|
"API returned an empty JSON response body", rawAPIJSONHint)
|
|
}
|
|
if isJSONDecodeError(err, true) {
|
|
return output.ErrWithHint(output.ExitAPI, "api_error",
|
|
fmt.Sprintf("API returned an invalid JSON response: %v", err), rawAPIJSONHint)
|
|
}
|
|
return output.ErrNetwork("API call failed: %v", err)
|
|
}
|
|
|
|
func isJSONDecodeError(err error, allowEOF bool) bool {
|
|
var syntaxErr *json.SyntaxError
|
|
var unmarshalTypeErr *json.UnmarshalTypeError
|
|
|
|
if errors.As(err, &syntaxErr) || errors.As(err, &unmarshalTypeErr) {
|
|
return true
|
|
}
|
|
if allowEOF && (errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF)) {
|
|
return true
|
|
}
|
|
|
|
msg := err.Error()
|
|
if allowEOF && strings.Contains(msg, "unexpected EOF") {
|
|
return true
|
|
}
|
|
return strings.Contains(msg, "unexpected end of JSON input") ||
|
|
strings.Contains(msg, "invalid character") ||
|
|
strings.Contains(msg, "cannot unmarshal")
|
|
}
|