capture

type Config struct {
	// BodyBytes bounds each stored body (1 KiB to 8 MiB). A larger body is
	// omitted in redacted mode and stored as an exact prefix in full mode.
	BodyBytes int
	// ValueBytes bounds a redacted string or field value (64 bytes to 1 MiB);
	// longer values read "[omitted N bytes]".
	ValueBytes int
	// ForceRedacted stores every client redacted, overriding
	// Builder.FullOutboundCapture.
	ForceRedacted bool
	// MaskNames adds credential names for headers, query values and body
	// fields, matched exactly and case-insensitively (at most 64, each 1 to
	// 128 bytes).
	MaskNames []string `config:",json"`
	// Exclude is the deny-list (at most 64 rules). A call matching any rule
	// is not captured.
	Exclude []Exclusion `config:",json"`
	// Rate admits at most this many captures per second per client per
	// process (1 to 10,000). Refused calls are made normally and counted as lost.
	Rate int
	// Burst is the per-client admission burst (1 to 10,000).
	Burst int
	// QueueRows bounds captures in flight, queued or being written per
	// process (1 to 256). One client may hold at most a quarter.
	QueueRows int
	// RetainedBytes bounds memory those captures hold per process (up to
	// 1 GiB). One client may hold at most a quarter, which must fit one body.
	RetainedBytes int64
	// Retention deletes captures older than this (1 hour to 365 days).
	Retention time.Duration
	// MaxRows keeps about this many newest captures per client (1,000 to
	// 10,000,000). Pruning catches up every minute while over the cap.
	MaxRows int
}

type Dependencies struct {
	DB *database.DB
	// Schema holds foundry_outbound_captures; it must be a valid identifier.
	Schema string
	// Clock supplies retention cutoffs. Attempt times come from the client.
	Clock  clock.Clock
	Logger *slog.Logger
}

type Exchange struct{}

type ExchangeID = model.ID[Exchange]

type Exclusion struct {
	// Client matches the client's configured name exactly. A rule with only a
	// client excludes that client entirely.
	Client httpclient.Name `json:"client,omitzero"`
	// Host matches the URL host without port, case-insensitively:
	// "api.example.com", or "*.example.com" for any subdomain (the apex needs
	// its own rule).
	Host string `json:"host,omitzero"`
	// Method matches the upper-case request method.
	Method string `json:"method,omitzero"`
	// PathPrefix matches the decoded path segment by segment; it is validated
	// like http.ParsePathPrefix.
	PathPrefix string `json:"path_prefix,omitzero"`
}

type Operation struct{}

type OperationID = model.ID[Operation]

type OutboundBodyOmission string

type OutboundBodyState string

type OutboundCapture struct {
	ID          ExchangeID  `json:"id"`
	OperationID OperationID `json:"operation_id"`
	// Attempt is 1 to 10, or 0 for a call that never reached the wire.
	Attempt int32 `json:"attempt"`
	// Retried means the client made another attempt after this one.
	Retried   bool              `json:"retried"`
	StartedAt temporal.DateTime `json:"started_at"`
	Client    httpclient.Name   `json:"client"`
	Method    string            `json:"method"`
	Host      string            `json:"host"`
	// Path is the escaped request path, at most 4 KiB.
	Path string `json:"path"`
	// Status is the response status; null when no response arrived.
	Status value.Nullable[int32] `json:"status"`
	Result OutboundResult        `json:"result"`
	// HeadersMS is the time to response headers; null without a response.
	HeadersMS  value.Nullable[int64] `json:"headers_ms"`
	DurationMS int64                 `json:"duration_ms"`
	// RequestID is the inbound request that made the call, if any.
	RequestID         value.Nullable[attribution.RequestID] `json:"request_id"`
	Mode              OutboundCaptureMode                   `json:"mode"`
	RequestSentBytes  int64                                 `json:"request_sent_bytes"`
	ResponseReadBytes int64                                 `json:"response_read_bytes"`
	// DroppedBefore counts captures of the same client the writing process
	// lost after its previous stored capture and before this one.
	DroppedBefore int64 `json:"dropped_before"`
}

type OutboundCaptureBody struct {
	State OutboundBodyState `json:"state"`
	// Omission is set exactly when State is omitted.
	Omission value.Nullable[OutboundBodyOmission] `json:"omission"`
	// DeclaredBytes is the Content-Length; null when unknown.
	DeclaredBytes value.Nullable[int64] `json:"declared_bytes"`
	// TransferredBytes is what the transport sent (request) or the caller
	// read (response).
	TransferredBytes int64 `json:"transferred_bytes"`
	// Complete means the end of the body was observed: the transport sent
	// the whole request body, or the caller read the whole response. An
	// in-memory request body is stored whole even when it is false.
	Complete bool   `json:"complete"`
	Content  []byte `json:"content"`
}

type OutboundCaptureBodyValidationFieldSet struct {
	// Complete validates the declared JSON property "complete".
	//
	// Complete means the end of the body was observed: the transport sent
	// the whole request body, or the caller read the whole response. An
	// in-memory request body is stored whole even when it is false.
	//
	Complete foundryvalidation.Field[OutboundCaptureBody, bool]
	// Content validates the declared JSON property "content".
	Content foundryvalidation.Field[OutboundCaptureBody, []byte]
	// DeclaredBytes validates the declared JSON property "declared_bytes".
	//
	// DeclaredBytes is the Content-Length; null when unknown.
	//
	DeclaredBytes foundryvalidation.Field[OutboundCaptureBody, foundryvalue.Nullable[int64]]
	// Omission validates the declared JSON property "omission".
	//
	// Omission is set exactly when State is omitted.
	//
	Omission foundryvalidation.Field[OutboundCaptureBody, foundryvalue.Nullable[OutboundBodyOmission]]
	// State validates the declared JSON property "state".
	State foundryvalidation.Field[OutboundCaptureBody, OutboundBodyState]
	// TransferredBytes validates the declared JSON property "transferred_bytes".
	//
	// TransferredBytes is what the transport sent (request) or the caller
	// read (response).
	//
	TransferredBytes foundryvalidation.Field[OutboundCaptureBody, int64]
}

type OutboundCaptureCause struct {
	RequestID value.Nullable[attribution.RequestID] `json:"request_id"`
	// TraceID is the W3C trace ID as 32 lowercase hexadecimal characters.
	TraceID value.Nullable[string] `json:"trace_id"`
	// Route is the matched inbound route's declared name.
	Route value.Nullable[string] `json:"route"`
}

type OutboundCaptureCauseValidationFieldSet struct {
	// RequestID validates the declared JSON property "request_id".
	RequestID foundryvalidation.Field[OutboundCaptureCause, foundryvalue.Nullable[attribution.RequestID]]
	// Route validates the declared JSON property "route".
	//
	// Route is the matched inbound route's declared name.
	//
	Route foundryvalidation.Field[OutboundCaptureCause, foundryvalue.Nullable[string]]
	// TraceID validates the declared JSON property "trace_id".
	//
	// TraceID is the W3C trace ID as 32 lowercase hexadecimal characters.
	//
	TraceID foundryvalidation.Field[OutboundCaptureCause, foundryvalue.Nullable[string]]
}

type OutboundCaptureDetail struct {
	Capture          OutboundCapture        `json:"capture"`
	Scheme           string                 `json:"scheme"`
	Query            []OutboundCaptureField `json:"query"`
	RequestHeaders   []OutboundCaptureField `json:"request_headers"`
	RequestBody      OutboundCaptureBody    `json:"request_body"`
	Protocol         value.Nullable[string] `json:"protocol"`
	RemoteIP         value.Nullable[string] `json:"remote_ip"`
	ConnectionReused value.Nullable[bool]   `json:"connection_reused"`
	// ResponseHeaders are the headers the client received, with credential
	// names such as Set-Cookie masked.
	ResponseHeaders []OutboundCaptureField `json:"response_headers"`
	ResponseBody    OutboundCaptureBody    `json:"response_body"`
	Cause           OutboundCaptureCause   `json:"cause"`
	// Attempts are the operation's other stored attempts, oldest first.
	Attempts  []OutboundCapture         `json:"attempts"`
	Omissions []OutboundCaptureOmission `json:"omissions"`
}

type OutboundCaptureDetailValidationFieldSet struct {
	// Attempts validates the declared JSON property "attempts".
	//
	// Attempts are the operation's other stored attempts, oldest first.
	//
	Attempts foundryvalidation.Field[OutboundCaptureDetail, []OutboundCapture]
	// Capture validates the declared JSON property "capture".
	Capture foundryvalidation.Field[OutboundCaptureDetail, OutboundCapture]
	// Cause validates the declared JSON property "cause".
	Cause foundryvalidation.Field[OutboundCaptureDetail, OutboundCaptureCause]
	// ConnectionReused validates the declared JSON property "connection_reused".
	ConnectionReused foundryvalidation.Field[OutboundCaptureDetail, foundryvalue.Nullable[bool]]
	// Omissions validates the declared JSON property "omissions".
	Omissions foundryvalidation.Field[OutboundCaptureDetail, []OutboundCaptureOmission]
	// Protocol validates the declared JSON property "protocol".
	Protocol foundryvalidation.Field[OutboundCaptureDetail, foundryvalue.Nullable[string]]
	// Query validates the declared JSON property "query".
	Query foundryvalidation.Field[OutboundCaptureDetail, []OutboundCaptureField]
	// RemoteIP validates the declared JSON property "remote_ip".
	RemoteIP foundryvalidation.Field[OutboundCaptureDetail, foundryvalue.Nullable[string]]
	// RequestBody validates the declared JSON property "request_body".
	RequestBody foundryvalidation.Field[OutboundCaptureDetail, OutboundCaptureBody]
	// RequestHeaders validates the declared JSON property "request_headers".
	RequestHeaders foundryvalidation.Field[OutboundCaptureDetail, []OutboundCaptureField]
	// ResponseBody validates the declared JSON property "response_body".
	ResponseBody foundryvalidation.Field[OutboundCaptureDetail, OutboundCaptureBody]
	// ResponseHeaders validates the declared JSON property "response_headers".
	//
	// ResponseHeaders are the headers the client received, with credential
	// names such as Set-Cookie masked.
	//
	ResponseHeaders foundryvalidation.Field[OutboundCaptureDetail, []OutboundCaptureField]
	// Scheme validates the declared JSON property "scheme".
	Scheme foundryvalidation.Field[OutboundCaptureDetail, string]
}

type OutboundCaptureField struct {
	Name   string   `json:"name"`
	Values []string `json:"values"`
}

type OutboundCaptureFieldValidationFieldSet struct {
	// Name validates the declared JSON property "name".
	Name foundryvalidation.Field[OutboundCaptureField, string]
	// Values validates the declared JSON property "values".
	Values foundryvalidation.Field[OutboundCaptureField, []string]
}

type OutboundCaptureFilters struct {
	From  temporal.DateTime                 `query:"from"`
	Until value.Optional[temporal.DateTime] `query:"until"`
	// Client matches the client name exactly.
	Client value.Optional[httpclient.Name] `query:"client"`
	// Host matches the stored host exactly, including a port when the URL had one.
	Host   value.Optional[string]         `query:"host"`
	Method value.Optional[string]         `query:"method"`
	Status value.Optional[int32]          `query:"status"`
	Result value.Optional[OutboundResult] `query:"result"`
	// Problems keeps attempts that did not complete or answered 400 or above.
	Problems value.Optional[bool] `query:"problems"`
	// RequestID keeps calls made while handling one inbound request.
	RequestID value.Optional[attribution.RequestID] `query:"request_id"`
	// Operation keeps the attempts of one call.
	Operation value.Optional[OperationID] `query:"operation"`
}

type OutboundCaptureMode string

type OutboundCaptureOmission string

type OutboundCapturePath struct {
	Capture ExchangeID `path:"capture"`
}

type OutboundCaptureValidationFieldSet struct {
	// Attempt validates the declared JSON property "attempt".
	//
	// Attempt is 1 to 10, or 0 for a call that never reached the wire.
	//
	Attempt foundryvalidation.Field[OutboundCapture, int32]
	// Client validates the declared JSON property "client".
	Client foundryvalidation.Field[OutboundCapture, httpclient.Name]
	// DroppedBefore validates the declared JSON property "dropped_before".
	//
	// DroppedBefore counts captures of the same client the writing process
	// lost after its previous stored capture and before this one.
	//
	DroppedBefore foundryvalidation.Field[OutboundCapture, int64]
	// DurationMS validates the declared JSON property "duration_ms".
	DurationMS foundryvalidation.Field[OutboundCapture, int64]
	// HeadersMS validates the declared JSON property "headers_ms".
	//
	// HeadersMS is the time to response headers; null without a response.
	//
	HeadersMS foundryvalidation.Field[OutboundCapture, foundryvalue.Nullable[int64]]
	// Host validates the declared JSON property "host".
	Host foundryvalidation.Field[OutboundCapture, string]
	// ID validates the declared JSON property "id".
	ID foundryvalidation.Field[OutboundCapture, model.ID[Exchange]]
	// Method validates the declared JSON property "method".
	Method foundryvalidation.Field[OutboundCapture, string]
	// Mode validates the declared JSON property "mode".
	Mode foundryvalidation.Field[OutboundCapture, OutboundCaptureMode]
	// OperationID validates the declared JSON property "operation_id".
	OperationID foundryvalidation.Field[OutboundCapture, model.ID[Operation]]
	// Path validates the declared JSON property "path".
	//
	// Path is the escaped request path, at most 4 KiB.
	//
	Path foundryvalidation.Field[OutboundCapture, string]
	// RequestID validates the declared JSON property "request_id".
	//
	// RequestID is the inbound request that made the call, if any.
	//
	RequestID foundryvalidation.Field[OutboundCapture, foundryvalue.Nullable[attribution.RequestID]]
	// RequestSentBytes validates the declared JSON property "request_sent_bytes".
	RequestSentBytes foundryvalidation.Field[OutboundCapture, int64]
	// ResponseReadBytes validates the declared JSON property "response_read_bytes".
	ResponseReadBytes foundryvalidation.Field[OutboundCapture, int64]
	// Result validates the declared JSON property "result".
	Result foundryvalidation.Field[OutboundCapture, OutboundResult]
	// Retried validates the declared JSON property "retried".
	//
	// Retried means the client made another attempt after this one.
	//
	Retried foundryvalidation.Field[OutboundCapture, bool]
	// StartedAt validates the declared JSON property "started_at".
	StartedAt foundryvalidation.Field[OutboundCapture, temporal.DateTime]
	// Status validates the declared JSON property "status".
	//
	// Status is the response status; null when no response arrived.
	//
	Status foundryvalidation.Field[OutboundCapture, foundryvalue.Nullable[int32]]
}

type OutboundResult string

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