mirror of
https://github.com/larksuite/cli.git
synced 2026-07-05 15:47:54 +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.
89 lines
3.1 KiB
Go
89 lines
3.1 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package errs
|
|
|
|
import (
|
|
"errors"
|
|
)
|
|
|
|
// ProblemOf extracts the embedded Problem via the non-exported problemCarrier interface.
|
|
// This is the supported way to read shared fields without depending on a specific typed error.
|
|
//
|
|
// A typed error whose embedded *Problem is nil is treated as "not a problem
|
|
// carrier" — returning (nil, true) here would cause CategoryOf / IsRetryable
|
|
// and other downstream readers to dereference nil.
|
|
func ProblemOf(err error) (*Problem, bool) {
|
|
var c problemCarrier
|
|
if errors.As(err, &c) {
|
|
if p := c.ProblemDetail(); p != nil {
|
|
return p, true
|
|
}
|
|
}
|
|
return nil, false
|
|
}
|
|
|
|
// UnwrapTypedError walks the wrap chain and returns the first error that
|
|
// embeds Problem (i.e. any typed error in this package). Returns the typed
|
|
// error itself (as error) so callers — notably JSON marshaling — see the
|
|
// concrete value's own struct tags rather than an opaque wrapper.
|
|
func UnwrapTypedError(err error) (error, bool) {
|
|
var c problemCarrier
|
|
if errors.As(err, &c) {
|
|
if e, ok := c.(error); ok {
|
|
return e, true
|
|
}
|
|
}
|
|
return nil, false
|
|
}
|
|
|
|
// CategoryOf returns the error's Category for metrics/logging/dispatch routing.
|
|
// Falls back to CategoryInternal for non-typed errors.
|
|
func CategoryOf(err error) Category {
|
|
if p, ok := ProblemOf(err); ok {
|
|
return p.Category
|
|
}
|
|
return CategoryInternal
|
|
}
|
|
|
|
// IsRetryable reads Problem.Retryable; non-typed errors are non-retryable by default.
|
|
func IsRetryable(err error) bool {
|
|
if p, ok := ProblemOf(err); ok {
|
|
return p.Retryable
|
|
}
|
|
return false
|
|
}
|
|
|
|
// IsValidation reports whether err is a *ValidationError.
|
|
func IsValidation(err error) bool { var x *ValidationError; return errors.As(err, &x) }
|
|
|
|
// IsPermission reports whether err is a *PermissionError.
|
|
func IsPermission(err error) bool { var x *PermissionError; return errors.As(err, &x) }
|
|
|
|
// IsNetwork reports whether err is a *NetworkError.
|
|
func IsNetwork(err error) bool { var x *NetworkError; return errors.As(err, &x) }
|
|
|
|
// IsAPI reports whether err is an *APIError.
|
|
func IsAPI(err error) bool { var x *APIError; return errors.As(err, &x) }
|
|
|
|
// IsSecurityPolicy reports whether err is a *SecurityPolicyError.
|
|
func IsSecurityPolicy(err error) bool { var x *SecurityPolicyError; return errors.As(err, &x) }
|
|
|
|
// IsContentSafety reports whether err is a *ContentSafetyError.
|
|
func IsContentSafety(err error) bool { var x *ContentSafetyError; return errors.As(err, &x) }
|
|
|
|
// IsInternal reports whether err is an *InternalError.
|
|
func IsInternal(err error) bool { var x *InternalError; return errors.As(err, &x) }
|
|
|
|
// IsConfirmationRequired reports whether err is a *ConfirmationRequiredError.
|
|
func IsConfirmationRequired(err error) bool {
|
|
var x *ConfirmationRequiredError
|
|
return errors.As(err, &x)
|
|
}
|
|
|
|
// IsAuthentication reports whether err is an *AuthenticationError.
|
|
func IsAuthentication(err error) bool { var x *AuthenticationError; return errors.As(err, &x) }
|
|
|
|
// IsConfig reports whether err is a *ConfigError.
|
|
func IsConfig(err error) bool { var x *ConfigError; return errors.As(err, &x) }
|