identity

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package identity holds the core-owned proxy identity policy model: upstream User-Agent / OpenRouter app attribution and downstream Server presentation.

Connector outbound application and A-leg Server middleware are out of scope; this package owns typed config, defaults, validation, and backend override merge.

Index

Constants

View Source 
const (
	DefaultProductName = "go-llm-interactive-proxy"
	DefaultProjectURL  = "https://github.com/matdev83/go-llm-interactive-proxy"
)

Literal product defaults for proxy identity presentation.

View Source 
const (
	MaxUserAgentBytes = 512
	MaxServerBytes    = 512
	MaxAppTitleBytes  = 256
	MaxAppURLBytes    = 2048
)

Field value bounds after trim.

Variables

This section is empty.

Functions

func AcceptClientAppTitle 

func AcceptClientAppTitle(raw string) (string, bool)

AcceptClientAppTitle returns a trimmed app title suitable for OpenRouter title passthrough. ok is false when blank, over MaxAppTitleBytes, or when the value contains control characters.

func AcceptClientAppURL 

func AcceptClientAppURL(raw string) (string, bool)

AcceptClientAppURL returns a trimmed absolute http(s) URL suitable for OpenRouter HTTP-Referer passthrough. ok is false when blank, over MaxAppURLBytes, control-laden, or not a valid absolute http(s) URL without userinfo or fragment.

func AcceptClientUserAgent 

func AcceptClientUserAgent(raw string) (string, bool)

AcceptClientUserAgent returns a trimmed User-Agent suitable for canonical invocation metadata. ok is false when blank, over MaxUserAgentBytes, or when the value contains CR/LF/NUL/control characters.

func ApplyDefaults 

func ApplyDefaults(cfg *Config)

ApplyDefaults fills empty/whitespace modes with ModeProxy. Proxy-mode values stay empty; resolved identity strings come from FieldPolicy.ResolvedValue. Validate calls this; prefer Validate for load paths. Nil cfg is a no-op.

func CallClientUserAgent 

func CallClientUserAgent(ctx context.Context) (ua string, ok bool)

CallClientUserAgent reports whether ctx is an Open call path and the carried UA. ok is false for unmarked contexts (default background) and for contexts wrapped with WithBackgroundIdentity.

func Validate 

func Validate(cfg *Config) error

Validate applies defaults, normalizes modes/values in place, and checks identity policy rules (modes, custom values, control characters, bounds, OpenRouter URL shape).

func ValidateBackendOverride 

func ValidateBackendOverride(ov *BackendOverride) error

ValidateBackendOverride validates every non-nil override field (including URL rules) and persists normalized mode/value into those fields. Nil override is OK.

func WithBackgroundIdentity 

func WithBackgroundIdentity(ctx context.Context) context.Context

WithBackgroundIdentity forces background/proxy identity resolution even when the parent context carries a call-path User-Agent. Use for inventory, token count, and other non-Open HTTP. A nil ctx is treated as context.Background().

func WithClientUserAgent 

func WithClientUserAgent(ctx context.Context, ua string) context.Context

WithClientUserAgent marks ctx as a B-leg Open call path and carries the captured A-leg User-Agent for passthrough resolution. An empty ua is valid and means "call path with no usable client identity" (omit under passthrough). A nil ctx is treated as context.Background().

Types

type BackendOverride 

type BackendOverride struct {
	UserAgent  *FieldPolicy        `yaml:"user_agent,omitempty"`
	OpenRouter *OpenRouterOverride `yaml:"openrouter,omitempty"`
}

BackendOverride is a partial backend identity override suitable for later standardplugin factory integration. Nil pointers inherit; non-nil applies explicitly (ModeDrop is distinct from omission).

type Config 

type Config struct {
	Upstream   UpstreamPolicy   `yaml:"upstream"`
	Downstream DownstreamPolicy `yaml:"downstream"`
}

Config is the root YAML identity subtree under identity:.

type DownstreamPolicy 

type DownstreamPolicy struct {
	Server FieldPolicy `yaml:"server"`
}

DownstreamPolicy configures A-leg (proxy -> client) identity presentation. Server allows proxy|custom|drop only (no passthrough).

type EffectiveDownstream 

type EffectiveDownstream struct {
	Server FieldPolicy
}

EffectiveDownstream is the resolved downstream policy after defaults.

func EffectiveDownstreamOf 

func EffectiveDownstreamOf(cfg Config) EffectiveDownstream

EffectiveDownstreamOf returns the resolved downstream identity policy. Zero-value configs receive defaults on a copy (cfg is not mutated).

func (EffectiveDownstream) ServerValue 

func (e EffectiveDownstream) ServerValue() string

ServerValue returns the proxy/custom Server header value.

type EffectiveUpstream 

type EffectiveUpstream struct {
	UserAgent FieldPolicy
	AppURL    FieldPolicy
	AppTitle  FieldPolicy
}

EffectiveUpstream is the resolved upstream policy after global defaults and optional backend override merge.

func MergeUpstream 

func MergeUpstream(global Config, override *BackendOverride) EffectiveUpstream

MergeUpstream resolves effective upstream identity from a global config and an optional partial backend override. Zero-value global configs receive defaults on a copy (the caller's global is not mutated). Nil override pointers inherit; non-nil policies (including ModeDrop) replace the corresponding field.

func (EffectiveUpstream) AppTitleValue 

func (e EffectiveUpstream) AppTitleValue() string

AppTitleValue returns the proxy/custom OpenRouter app title for the field.

func (EffectiveUpstream) AppURLValue 

func (e EffectiveUpstream) AppURLValue() string

AppURLValue returns the proxy/custom OpenRouter app URL for the field.

func (EffectiveUpstream) UserAgentValue 

func (e EffectiveUpstream) UserAgentValue() string

UserAgentValue returns the proxy/custom User-Agent string for the field.

type FieldPolicy 

type FieldPolicy struct {
	Mode  Mode   `yaml:"mode"`
	Value string `yaml:"value"`
}

FieldPolicy is one configurable identity carrier (mode + optional custom value).

func (FieldPolicy) ResolvedValue 

func (f FieldPolicy) ResolvedValue(proxyDefault string) string

ResolvedValue returns the concrete identity string for emission when the mode produces a fixed value (proxy or custom). Passthrough and drop return "".

type IdentityScenarioSpec 

type IdentityScenarioSpec struct {
	ID               string
	InvariantSummary string
	TestName         string
	PackageRel       string
}

IdentityScenarioSpec links a stable scenario identifier to proxy-identity invariants (issue #147) and the primary regression test (specification bundle). PackageRel is the repository-relative directory that owns TestName's *_test.go (may live in an external connector module under connectors/, outside the root go.mod).

func SpecBundleIdentityScenarios 

func SpecBundleIdentityScenarios() []IdentityScenarioSpec

SpecBundleIdentityScenarios lists A-leg/B-leg identity invariants. Keep aligned with the referenced tests and docs/proxy-identity.md.

type Mode 

type Mode string

Mode selects how an identity field is produced or suppressed. 

const (
	// ModeProxy emits the configured LIP product identity (or field default).
	ModeProxy Mode = "proxy"
	// ModePassthrough forwards the client-supplied value when available.
	ModePassthrough Mode = "passthrough"
	// ModeCustom emits FieldPolicy.Value.
	ModeCustom Mode = "custom"
	// ModeDrop omits the header/field entirely.
	ModeDrop Mode = "drop"
)

type OpenRouterOverride 

type OpenRouterOverride struct {
	AppURL   *FieldPolicy `yaml:"app_url,omitempty"`
	AppTitle *FieldPolicy `yaml:"app_title,omitempty"`
}

OpenRouterOverride is a partial OpenRouter attribution override for one backend. Nil field pointers mean inherit from the global policy; a non-nil pointer (including ModeDrop) replaces that field.

type OpenRouterPolicy 

type OpenRouterPolicy struct {
	AppURL   FieldPolicy `yaml:"app_url"`
	AppTitle FieldPolicy `yaml:"app_title"`
}

OpenRouterPolicy configures OpenRouter HTTP-Referer / X-OpenRouter-Title app attribution. Vendor wire details stay adapter-local; these are proxy-wide policy knobs only.

type UpstreamPolicy 

type UpstreamPolicy struct {
	UserAgent  FieldPolicy      `yaml:"user_agent"`
	OpenRouter OpenRouterPolicy `yaml:"openrouter"`
}

UpstreamPolicy configures B-leg (proxy -> backend) identity presentation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.