{"record":{"id":"6c39ebfbc0f5ddb2","repo":"larksuite/cli","slug":"connection-check-w","errorCode":null,"errorMessage":"connection check: %w","messagePattern":"connection check: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/event/consume/remote_preflight.go","lineNumber":20,"sourceCode":"// SPDX-License-Identifier: MIT\n\npackage consume\n\nimport (\n\t\"context\"\n\t\"encoding/json\"\n\t\"fmt\"\n\n\t\"github.com/larksuite/cli/internal/event\"\n)\n\ntype APIClient = event.APIClient\n\n// CheckRemoteConnections returns the count of active WebSocket connections for this app.\nfunc CheckRemoteConnections(ctx context.Context, client APIClient) (int, error) {\n\traw, err := client.CallAPI(ctx, \"GET\", \"/open-apis/event/v1/connection\", nil)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"connection check: %w\", err)\n\t}\n\tvar result struct {\n\t\tCode int    `json:\"code\"`\n\t\tMsg  string `json:\"msg\"`\n\t\tData struct {\n\t\t\tOnlineInstanceCnt int `json:\"online_instance_cnt\"`\n\t\t} `json:\"data\"`\n\t}\n\tif err := json.Unmarshal(raw, &result); err != nil {\n\t\treturn 0, fmt.Errorf(\"connection check: decode: %w (body=%s)\", err, truncateForError(raw))\n\t}\n\t// Distinguish \"verified zero\" from \"check failed\" — non-zero code decodes Cnt=0.\n\tif result.Code != 0 {\n\t\treturn 0, fmt.Errorf(\"connection check: api error code=%d msg=%q\", result.Code, result.Msg)\n\t}\n\treturn result.Data.OnlineInstanceCnt, nil\n}\n","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/internal/event/consume/remote_preflight.go#L2-L38","documentation":"CheckRemoteConnections performs a preflight GET to /open-apis/event/v1/connection to count active WebSocket long-connection instances for the app. When the underlying APIClient.CallAPI transport/network call fails (unreachable host, auth rejection, timeout, non-2xx handled at the transport layer), the error is wrapped as 'connection check: %w' so the caller sees the preflight context plus the root cause. It deliberately returns count 0 with the error, since the check failed rather than being verified as zero.","triggerScenarios":"Any CallAPI error on GET /open-apis/event/v1/connection during remote preflight: network unreachable, DNS failure, TLS error, HTTP timeout, invalid tenant access token, or 4xx/5xx responses surfaced by the client's error path.","commonSituations":"Offline or restricted CI environments running a consumer that dials the bus, expired or missing app credentials, wrong domain/base-URL configuration, corporate proxy blocking the endpoint, firewall dropping outbound HTTPS.","solutions":["Run the same GET /open-apis/event/v1/connection with curl using the app's credentials to confirm the endpoint is reachable.","Check that the app credentials (app_id/app_secret or token) are valid and not expired; refresh the token.","Verify network/proxy/DNS settings allow HTTPS to the Lark/Feishu open domain.","Unwrap with errors.Unwrap or errors.As to read the root cause and apply the matching transport fix."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Preflight reachability check before invoking CheckRemoteConnections\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\ndefer cancel()\nreq, _ := http.NewRequestWithContext(ctx, http.MethodGet,\n\tbaseURL+\"/open-apis/event/v1/connection\", nil)\nif _, err := http.DefaultClient.Do(req); err != nil {\n\t// abort early: network/credentials are broken\n}","typeGuard":null,"tryCatchPattern":"cnt, err := consume.CheckRemoteConnections(ctx, client)\nif err != nil {\n\tvar apiErr *errs.APIError // or the concrete client error type\n\tif errors.As(err, &apiErr) {\n\t\t// inspect status/code; retry only transient categories\n\t}\n\tif !isRetryable(err) { return fmt.Errorf(\"preflight aborted: %w\", err) }\n}","preventionTips":["Validate credentials (token freshness) before starting consumers.","Run in an environment with verified outbound HTTPS to the open domain; set proxy vars explicitly in CI.","Apply bounded exponential backoff retries for transient transport errors.","Surface unwrapped root causes in logs to distinguish network vs auth failures."],"tags":["network","http","preflight","websocket"],"backgroundTag":"api-call-failed","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}