mirror of
https://github.com/larksuite/cli.git
synced 2026-07-03 14:02:43 +08:00
99e314fe0b
Every failure on the authentication, authorization, and configuration
path now surfaces as a typed structured error instead of an ad-hoc
envelope. Users and scripts that consume CLI output get:
- a fixed nine-category taxonomy on the wire, each mapped to a
stable shell exit code (authentication/authorization/config = 3,
network = 4, internal = 5, policy = 6, confirmation = 10)
- identity-aware detail fields (missing_scopes, requested_scopes,
granted_scopes, console_url, log_id, retryable, hint) carried
uniformly on the envelope
- a single canonical policy envelope at exit 6; the legacy
auth_error carve-out is retired
- per-subtype canonical message + hint that preserves Lark's
diagnostic phrasing and routes recovery to the right actor:
app developer (app_scope_not_applied), user (missing_scope,
token_scope_insufficient, user_unauthorized), or tenant admin
(app_unavailable, app_disabled)
- wrong app credentials classify as config/invalid_client whether
surfaced by the Open API endpoint (99991543) or the tenant
access-token mint endpoint (10003 / 10014), instead of
collapsing to a transport error or api/unknown
- local shortcut scope preflight emits the same
authorization/missing_scope envelope (identity + deterministic
missing-scope set) used by the post-call permission path, so AI
consumers read the same structured shape from precheck and from
server-returned permission denial
- streaming download/upload failures keep the same network subtype
split (timeout / TLS / DNS / transport) as the non-stream path
instead of collapsing every cause to a generic transport failure
- console_url is carried only on the bot-perspective
app_scope_not_applied envelope (where the recovery action is
"developer applies the scope at the developer console"); the
user-perspective missing_scope envelope drops the field, since
the only actionable user recovery is `lark-cli auth login --scope`
and pointing an end user at a console they cannot modify is
misleading
- bind workflows (Hermes / OpenClaw / lark-channel) flatten dynamic
Type tags to wire 'config' with the original module name kept
as a metric label
All 10 typed errors are cause-bearing, nil-safe on .Error() and
.Unwrap(), and defensively clone slice setter inputs. Four lint
rules (CheckNilSafeError / CheckBuilderImmutable / CheckUnwrapSymmetry
/ CheckBuildAPIErrorArms) lock these invariants on migrated paths.
44 lines
1.8 KiB
Go
44 lines
1.8 KiB
Go
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package errs
|
|
|
|
// Problem is the RFC 7807-aligned shared shape embedded by every typed error.
|
|
//
|
|
// Message is REQUIRED. Producers must populate it; an empty Message will make
|
|
// Error() return "" — a known Go footgun for fmt.Errorf("...: %v", err).
|
|
//
|
|
// Wire-format notes:
|
|
// - No Component field. Service / shortcut component is metric-only
|
|
// enrichment derived by the dispatcher from the cobra command path; it
|
|
// never appears on the wire.
|
|
// - No DocURL field. PermissionError carries the same intent via its typed
|
|
// ConsoleURL extension; other typed errors do not link out.
|
|
// - Troubleshooter is the upstream Lark API's diagnostic URL (resp.error.
|
|
// troubleshooter). Carried universally so any classified error can surface
|
|
// it; populated by errclass.BuildAPIError when the upstream response
|
|
// includes it, otherwise absent.
|
|
// - Retryable uses omitempty so only `true` is emitted; consumers treat
|
|
// absence as false.
|
|
type Problem struct {
|
|
Category Category `json:"type"`
|
|
Subtype Subtype `json:"subtype,omitempty"`
|
|
Code int `json:"code,omitempty"`
|
|
Message string `json:"message"`
|
|
Hint string `json:"hint,omitempty"`
|
|
LogID string `json:"log_id,omitempty"`
|
|
Troubleshooter string `json:"troubleshooter,omitempty"`
|
|
Retryable bool `json:"retryable,omitempty"`
|
|
}
|
|
|
|
// Error satisfies the standard `error` interface. A nil receiver is treated
|
|
// as the empty string so a stray nil *Problem stored in an error interface
|
|
// cannot panic the dispatcher.
|
|
func (p *Problem) Error() string {
|
|
if p == nil {
|
|
return ""
|
|
}
|
|
return p.Message
|
|
}
|
|
func (p *Problem) ProblemDetail() *Problem { return p }
|