transport

Documentation

Overview

Package transport owns how the CLI assembles its outbound HTTP transport: the shared base RoundTripper (Shared/Fallback/NewHTTPClient), the LARK_CLI_NO_PROXY direct-egress clone, and the ~/.lark-cli/proxy_config.json proxy-plugin mode.

Proxy-plugin mode forces all outbound HTTP(S) requests through a fixed loopback proxy, optionally trusting an extra root CA PEM bundle for TLS-inspection proxies, and fails closed on misconfiguration. Environment variables override matching values from proxy_config.json.

Index

• Constants
• func DetectProxyEnv() (key, value string)
• func Fallback() *http.Transport
• func NewHTTPClient(timeout time.Duration) *http.Client
• func Path() string
• func Shared() http.RoundTripper
• func WarnIfProxied(w io.Writer)
• type Config
  • func Load() (*Config, error)
  • func (c *Config) ApplyToTransport(base *http.Transport) (*http.Transport, error)
  • func (c *Config) Enabled() bool

Constants

const (
	ConfigFileName = "proxy_config.json"
)

ConfigFileName is the fixed config file name under core.GetConfigDir().

const (
	// EnvNoProxy disables automatic proxy support when set to any non-empty value.
	EnvNoProxy = "LARK_CLI_NO_PROXY"
)

Proxy environment constants control shared transport proxy behavior.

Functions

func DetectProxyEnv

func DetectProxyEnv() (key, value string)

DetectProxyEnv returns the first proxy-related environment variable that is set, or empty strings if none are configured.

func Fallback

func Fallback() *http.Transport

Fallback returns a shared *http.Transport. It is a thin wrapper over Shared retained so modules already on the leak-free singleton path (internal/auth, internal/cmdutil transport decorators) do not have to migrate. New code should prefer Shared and treat the base as an http.RoundTripper.

Fail-closed invariant: pluginTransport always expresses its blocked transport as a concrete *http.Transport (see failClosedTransport), so the assertion below preserves the block. The noProxyTransport() fallback is therefore only reached when no proxy plugin is configured and some external code replaced http.DefaultTransport with a non-*http.Transport — a case with no fail-closed intent, where a proxy-disabled transport is acceptable.

func NewHTTPClient

func NewHTTPClient(timeout time.Duration) *http.Client

NewHTTPClient returns an *http.Client whose Transport is the shared, proxy-plugin-aware base (see Shared). Prefer this over a bare &http.Client{} for outbound requests: a bare client falls back to http.DefaultTransport and therefore silently bypasses proxy plugin mode (fixed proxy + trusted CA, or fail-closed), creating an audit blind spot.

A zero timeout means no client-level timeout (callers relying on context deadlines pass 0).

func Path

func Path() string

Path returns the absolute path to the proxy plugin config file.

func Shared

func Shared() http.RoundTripper

Shared returns the base http.RoundTripper for all CLI HTTP clients.

Precedence (highest first):

1. proxy-plugin mode — force traffic through a fixed loopback proxy; FAIL-CLOSED when the plugin config exists but is invalid.
2. LARK_CLI_NO_PROXY — direct egress, proxy disabled.
3. http.DefaultTransport — the stdlib process-wide singleton (honors HTTP(S)_PROXY), so every client shares one connection pool / TLS cache.

The returned RoundTripper MUST NOT be mutated. Callers that need a customized transport should assert to *http.Transport and Clone() it. A shared base is required so persistConn read/write goroutines are reused; cloning per call leaks them until IdleConnTimeout (~90s) fires.

func WarnIfProxied

func WarnIfProxied(w io.Writer)

WarnIfProxied prints a one-time warning to w when a proxy environment variable is detected and proxy is not disabled via LARK_CLI_NO_PROXY. Proxy credentials are redacted. Safe to call multiple times; only the first call prints.

Types

type Config

type Config struct {
	// Enable turns on proxy plugin transport handling.
	Enable bool `json:"LARKSUITE_CLI_PROXY_ENABLE"`

	// Proxy is the fixed HTTP proxy address used for all outbound requests.
	Proxy string `json:"LARKSUITE_CLI_PROXY_ADDRESS"`

	// CAPath points to an extra PEM bundle trusted for proxy TLS interception.
	CAPath string `json:"LARKSUITE_CLI_CA_PATH"`
}

Config is the on-disk config format. Keys intentionally mirror env var names.

func Load

func Load() (*Config, error)

Load reads ~/.lark-cli/proxy_config.json once and caches the parsed result. Environment variables (CliProxyEnable/CliProxyAddress/CliCAPath) take precedence over config file values.

Returns (nil, nil) only when:

• the config file does not exist AND
• none of the proxy-related env vars are present.

func (*Config) ApplyToTransport

func (c *Config) ApplyToTransport(base *http.Transport) (*http.Transport, error)

ApplyToTransport clones base and applies proxy plugin settings to the clone. Caller owns the returned *http.Transport.

func (*Config) Enabled

func (c *Config) Enabled() bool

Enabled reports whether proxy plugin mode is enabled.