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
- type Decision
- type FailModeRules
- type FallbackAuditWriter
- type GateFlags
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.
Variables ¶
This section is empty.
Functions ¶
func FirstStringArg ¶
FirstStringArg returns the first non-empty string value found in args under any of the supplied keys, or "" if none match.
func InferFilesystemAction ¶
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 ¶
ResolveAPIKey returns the explicit flag value when set, otherwise the AGENTGUARD_API_KEY env var.
func ValidateBaseURL ¶
ValidateBaseURL enforces that v has an http(s) scheme + host. Empty paths are accepted (concrete paths are joined at request time).
func ValidateGateConfig ¶
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 ¶
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).
Source Files