gateclient

Documentation

Overview

Package gateclient is the shared /v1/check client substrate for the LLM API Proxy (pkg/llmproxy) and the MCP Gateway (pkg/mcpgw). Both gates speak the same wire contract — POST a policy.ActionRequest to the central server, decode the policy.CheckResult, translate transport failures per --fail-mode — so that contract lives here once. Each proxy keeps only its own scope-mapping and argument- projection logic.

The package is internal: it is implementation substrate, not public API. The proxies re-export the pieces that are part of their stable contracts (Decision via type alias, the FailModeRule* constants).

Index

• Constants
• func FirstStringArg(args map[string]interface{}, keys ...string) string
• func InferFilesystemAction(toolName string) string
• func ResolveAPIKey(flagValue string) string
• func ValidateBaseURL(name, v string) error
• func ValidateGateConfig(guardURL, tenantID, failMode, logLevel string) error
• type Caller
  • func (c *Caller) CallV1Check(ctx context.Context, ar policy.ActionRequest, rules FailModeRules) (Decision, error)
• type Decision
  • func DecisionFromCheckResult(cr policy.CheckResult, rules FailModeRules) Decision
  • func FailModeDecision(failMode string, err error, rules FailModeRules) Decision
• type FailModeRules
• type FallbackAuditWriter
  • func NewFallbackAuditWriter(path string) *FallbackAuditWriter
  • func (w *FallbackAuditWriter) Record(ar policy.ActionRequest, d Decision, transport, tenantID string)
• type GateFlags
  • func RegisterGateFlags(fs *flag.FlagSet, policyHelp string) *GateFlags
  • func (f *GateFlags) Resolve() error

Constants

const (
	DefaultGuardURL = "http://127.0.0.1:8080"
	DefaultTenantID = "local"
	DefaultFailMode = "deny"
	DefaultLogLevel = "info"
)

Default values for the shared gate flags. Both proxies document the same defaults in docs/PROXY_ARCHITECTURE.md § 6.

const DefaultFailAuditLog = "agentguard-fail-audit.jsonl"

DefaultFailAuditLog is where fail-closed-with-audit denials are recorded locally when the central server is unreachable. Only ever created in that mode, and only when a check actually fails.

const DefaultGuardHTTPTimeout = 5 * time.Second

DefaultGuardHTTPTimeout is the per-/v1/check-call timeout applied when the operator does not pass a custom http.Client. Five seconds matches the SDKs and docs/PROXY_ARCHITECTURE.md § 6.1.

const FallbackFileMode = 0o600

FallbackFileMode matches the audit overflow file's permissions.

Functions

func FirstStringArg

func FirstStringArg(args map[string]interface{}, keys ...string) string

FirstStringArg returns the first non-empty string value found in args under any of the supplied keys, or "" if none match.

func InferFilesystemAction

func InferFilesystemAction(toolName string) string

InferFilesystemAction maps a tool-name verb to the canonical filesystem-scope action ("read"/"write"/"delete"). Best-effort — rules that match by Path only are unaffected.

func ResolveAPIKey

func ResolveAPIKey(flagValue string) string

ResolveAPIKey returns the explicit flag value when set, otherwise the AGENTGUARD_API_KEY env var.

func ValidateBaseURL

func ValidateBaseURL(name, v string) error

ValidateBaseURL enforces that v has an http(s) scheme + host. Empty paths are accepted (concrete paths are joined at request time).

func ValidateGateConfig

func ValidateGateConfig(guardURL, tenantID, failMode, logLevel string) error

ValidateGateConfig enforces the invariants shared by every gate binary. Exposed separately from Resolve so config structs built directly in tests can validate without a FlagSet.

Types

type Caller

type Caller struct {
	GuardURL   string
	APIKey     string
	TenantID   string
	UserAgent  string
	HTTPClient *http.Client
}

Caller is the wire-level /v1/check client. Zero-value fields are tolerated: an empty TenantID falls back to "local", a nil HTTPClient gets the default timeout.

func (*Caller) CallV1Check

func (c *Caller) CallV1Check(ctx context.Context, ar policy.ActionRequest, rules FailModeRules) (Decision, error)

CallV1Check POSTs ar to <GuardURL>/v1/t/<TenantID>/check and decodes the CheckResult into a Decision. Errors are returned for the caller to translate via FailModeDecision. SchemaVersion is stamped "v1" when the caller left it empty (the central server's request validator requires it).

type Decision

type Decision struct {
	Allow            bool
	RequiresApproval bool
	Reason           string
	Rule             string
	ApprovalID       string // set when REQUIRE_APPROVAL
	ApprovalURL      string
}

Decision is the verdict a gate returns to its proxy. pkg/llmproxy and pkg/mcpgw alias this type, so it is one shape across both binaries and the refusal/error-surfacing helpers on each side.

func DecisionFromCheckResult

func DecisionFromCheckResult(cr policy.CheckResult, rules FailModeRules) Decision

DecisionFromCheckResult maps a policy.CheckResult onto the Decision shape. An unrecognised decision string is treated as a hard DENY stamped with rules.Invalid so dashboards can alert on it.

func FailModeDecision

func FailModeDecision(failMode string, err error, rules FailModeRules) Decision

FailModeDecision returns the synthetic Decision dictated by --fail-mode when /v1/check is unreachable or returns malformed bytes.

type FailModeRules

type FailModeRules struct {
	Open        string // --fail-mode allow
	Closed      string // --fail-mode deny (default)
	ClosedAudit string // --fail-mode fail-closed-with-audit
	Invalid     string // /v1/check returned an unrecognised decision
}

FailModeRules carries the synthetic Rule strings a gate stamps on decisions it manufactures itself (fail-mode translations and malformed /v1/check responses). The values are per-binary stable contracts — dashboards alert on them — so each proxy supplies its own set.

type FallbackAuditWriter

type FallbackAuditWriter struct {
	// contains filtered or unexported fields
}

FallbackAuditWriter appends deny records to a local JSONL file. A nil writer is valid and records nothing — callers never need to nil-check.

The writer only runs on the /v1/check FAILURE path (central server unreachable), so the file append is not hot-path work. Append failures are logged to stderr (once per process, then counted silently) and never affect the policy decision.

func NewFallbackAuditWriter

func NewFallbackAuditWriter(path string) *FallbackAuditWriter

NewFallbackAuditWriter returns a writer appending to path, or nil when path is empty (feature disabled).

func (*FallbackAuditWriter) Record

func (w *FallbackAuditWriter) Record(ar policy.ActionRequest, d Decision, transport, tenantID string)

Record appends one audit entry for a fail-mode decision. transport is the proxy's audit transport tag ("llm_api_proxy" / "mcp_gateway"); tenantID is the gate's configured tenant.

type GateFlags

type GateFlags struct {
	GuardURL     *string
	APIKey       *string
	TenantID     *string
	FailMode     *string
	LogLevel     *string
	PolicyPath   *string
	FailAuditLog *string
}

GateFlags holds the destination pointers of the CLI flags every gate binary shares. Register on a FlagSet via RegisterGateFlags; after fs.Parse, apply the env fallback + validation via Resolve.

func RegisterGateFlags

func RegisterGateFlags(fs *flag.FlagSet, policyHelp string) *GateFlags

RegisterGateFlags registers the shared gate flags on fs. policyHelp is binary-specific because the two proxies document different behaviour for a missing --policy (the LLM proxy falls back to the bundled scope map; the MCP gateway requires it in strict mode).

func (*GateFlags) Resolve

func (f *GateFlags) Resolve() error

Resolve applies the env fallback and validates the shared invariants. Call after fs.Parse. The flag-wins-over-env API-key contract matches the agentguard core CLI.