api

type DXAPI struct {
	Version                      string
	NameId                       string
	Address                      string
	WriteTimeoutSec              int
	ReadTimeoutSec               int
	CORSAllowedOrigins           string // comma-separated allowed origins; empty or "*" = allow all
	EnableBrowserSecurityHeaders bool   // when true, adds X-Content-Type-Options, HSTS, X-Frame-Options
	EndPoints                    []DXAPIEndPoint
	RawHandlers                  []struct {
		Pattern string
		Handler http.Handler
	}
	// TLS is the server's TLS state, built from the "tls" block beside
	// "address" in the api configuration. nil means the block is absent and the
	// listener is plaintext, exactly as before the block existed. A block with
	// enabled=false leaves this non-nil with a nil Config, so the settings can
	// still be reported.
	TLS                      *utilsTLS.DXServerTLS
	RuntimeIsActive          bool
	HTTPServer               *http.Server
	Log                      log.DXLog
	Context                  context.Context
	Cancel                   context.CancelFunc
	OnAuditLogStart          DXAuditLogHandler
	OnAuditLogUserIdentified DXAuditLogHandler
	OnAuditLogEnd            DXAuditLogHandler

	// ProblemDetailsEnabled answers every refusal (status 400 and above) with an
	// RFC 9457 problem document (application/problem+json) instead of
	// {status, status_code, reason, reason_message}. Off by default.
	ProblemDetailsEnabled bool
	// ProblemTypeBaseURI is put in front of the reason code to name a problem
	// type, as in "https://example.com/problems/" + "UNIQUE_FIELD_VIOLATION".
	ProblemTypeBaseURI string
	// OmitServerErrorCause keeps the underlying error text out of a 5xx answer,
	// for an API that faces callers who must not see table names, SQL or hosts.
	// The answer still names the operation, what to do next and the
	// error_log_ref; its cause says where the full error is logged. A 4xx answer
	// always carries its cause. Off by default ("omit-server-error-cause").
	OmitServerErrorCause bool
}

type DXAPIAuditLogEntry struct {
	StartTime    time.Time `json:"start_time,omitempty"`
	EndTime      time.Time `json:"end_time,omitempty"`
	IPAddress    string    `json:"ip_address,omitempty"`
	UserId       string    `json:"user_id,omitempty"`
	UserUid      string    `json:"user_uid,omitempty"`
	UserLoginId  string    `json:"user_loginid,omitempty"`
	UserFullName string    `json:"user_fullname,omitempty"`
	APIURL       string    `json:"api_url,omitempty"`
	APITitle     string    `json:"api_title,omitempty"`
	Method       string    `json:"method,omitempty"`
	StatusCode   int       `json:"status_code,omitempty"`
	ErrorMessage string    `json:"error_message,omitempty"`
	// PeerIdentity is the caller as named by the verified client certificate,
	// when the request arrived over mTLS; empty otherwise. Under direct mTLS
	// there is no proxy in front to set X-Proxy-Client-IP, so IPAddress above
	// is whatever the caller put in X-Forwarded-For and this field is the one
	// that was actually authenticated. See GetIPAddress.
	PeerIdentity string `json:"peer_identity,omitempty"`
}

type DXAPIDomainError interface {
	error
	DomainErrorCode() string
	DomainErrorHTTPStatusCode() int
	DomainErrorResponseBody() utils.JSON
	DomainErrorLogDetails() string
}

type DXAPIEndPoint struct {
	Owner              *DXAPI
	Title              string
	Uri                string
	Method             string
	EndPointType       DXAPIEndPointType
	Description        string
	RequestContentType utilsHttp.RequestContentType
	Parameters         []DXAPIEndPointParameter
	OnExecute          DXAPIEndPointExecuteFunc
	OnWSLoop           DXAPIEndPointExecuteFunc

	// The hooks below drive the built-in WebSocket loop, used when OnWSLoop is
	// nil. Each application differs only in what it does on open and close and
	// in how it reads and writes a message, so those are all that is left to
	// supply; the read loop, write pump, keepalive and client registry are the
	// same everywhere and live in the library.
	OnWSOpen           DXAPIEndPointWSOpenFunc
	OnWSMessage        DXAPIEndPointWSMessageFunc
	OnWSClose          DXAPIEndPointWSCloseFunc
	OnWSPeriodic       DXAPIEndPointWSPeriodicFunc
	WSPeriodicInterval time.Duration

	ResponsePossibilities   *DXAPIEndPointResponsePossibilities
	Middlewares             []DXAPIEndPointExecuteFunc
	Privileges              []string
	RequestMaxContentLength int64
	RateLimitGroupNameId    string

	// IdempotencyKey is the request header that carries the endpoint's
	// idempotency key, nil when it takes none. NameId is the header name,
	// IsMustExist whether every request must send it, Type a string type and
	// the string bounds its format. It is set with SetEndPointIdempotencyKey
	// or bound from a document, and checked by PreProcessRequest; see
	// api_endpoint_idempotency.go.
	IdempotencyKey *DXAPIEndPointParameter
	// contains filtered or unexported fields
}

type DXAPIEndPointExecuteFunc func(aepr *DXAPIEndPointRequest) (err error)

type DXAPIEndPointParameter struct {
	Owner       *DXAPIEndPoint
	Parent      *DXAPIEndPointParameter
	NameId      string
	Type        dxlibTypes.APIParameterType
	Description string
	IsMustExist bool
	IsNullable  bool
	Children    []DXAPIEndPointParameter
	Enum        []any

	// The JSON Schema bounds Validate checks beyond what Type implies. Each is
	// off when nil (or empty, or false), so a declaration that sets none
	// behaves as before. A bound applies to the values of its own kind only:
	// the numeric bounds to the integer and number types, the length bounds
	// and Pattern to the string types, the item bounds to the array types.
	// Pattern is Go RE2 syntax and, as in JSON Schema, matches anywhere in the
	// string unless anchored. OPENAPI.md section 2.4 has the rules.
	Minimum          *float64
	ExclusiveMinimum *float64
	Maximum          *float64
	ExclusiveMaximum *float64
	MultipleOf       *float64
	MinLength        *int
	MaxLength        *int
	Pattern          string
	MinItems         *int
	MaxItems         *int
	UniqueItems      bool
	// Const holds the one value accepted; a nil pointer means no const.
	Const *any

	// The JSON Schema annotations. They describe the parameter to a reader of
	// the generated document and promise no check: request validation ignores them, a
	// Default is not filled in for a parameter left out, a ReadOnly parameter
	// is still read from the request (and still required when IsMustExist),
	// and nothing strips a WriteOnly value from a response. Default is a
	// scalar of the parameter's own JSON type; a nil pointer means none.
	// ReadOnly and WriteOnly may not both be set. OPENAPI.md section 2.4.
	Title     string
	Default   *any
	ReadOnly  bool
	WriteOnly bool
}

type DXAPIEndPointRequest struct {
	Id                 string
	Context            context.Context
	EndPoint           *DXAPIEndPoint
	ParameterValues    map[string]*DXAPIEndPointRequestParameterValue
	Log                log.DXLog
	Request            *http.Request
	RequestBodyAsBytes []byte
	ResponseWriter     *http.ResponseWriter

	ResponseStatusCode     int
	ErrorMessage           []string
	CurrentUser            DXAPIUser
	LocalData              utils.JSON
	ResponseHeaderSent     bool
	ResponseBodySent       bool
	SuppressLogDump        bool
	EncryptionParameters   utils.JSON
	EffectiveRequestHeader map[string]string
	DecryptedRequestBody   utils.JSON // E2E decrypted body for debug logging
	WSClient               *DXAPIEndPointWebSocketClient

	// PeerCertificate is the caller's leaf certificate, present only when the
	// request arrived over TLS and the server VERIFIED the certificate against
	// its ca-trust pool -- mode mtls, enforcing or on its verify-if-given rung.
	// It is nil on plaintext, nil when no certificate was sent, and nil under
	// mode https or the request rung even if a certificate was sent, because
	// there Go leaves it in r.TLS.PeerCertificates unverified and an
	// unverified certificate is a claim, not an identity. Middlewares and
	// OnBeforePreProcessRequest can make per-caller decisions on it; a
	// rejection there is after the handshake, so the allow-list in the tls
	// block is the place for anything that should never reach a handler.
	PeerCertificate *x509.Certificate
	// PeerIdentity is PeerCertificate reduced to one string (first URI SAN,
	// else first DNS SAN, else first IP SAN, else CN); "" when PeerCertificate
	// is nil. It is what the audit log carries.
	PeerIdentity string
	// IdempotencyKey is the value of the endpoint's idempotency key header,
	// checked against its declaration; "" when the endpoint takes none or the
	// request did not send an optional one.
	IdempotencyKey string
	// contains filtered or unexported fields
}

type DXAPIEndPointRequestParameterValue struct {
	Owner           *DXAPIEndPointRequest
	Parent          *DXAPIEndPointRequestParameterValue
	Value           any
	RawValue        any
	Metadata        DXAPIEndPointParameter
	IsArrayChildren bool
	Children        map[string]*DXAPIEndPointRequestParameterValue
	ArrayChildren   []DXAPIEndPointRequestParameterValue
	// contains filtered or unexported fields
}

type DXAPIEndPointResponsePossibilities map[string]DXAPIEndPointResponsePossibility

type DXAPIEndPointResponsePossibility struct {
	Owner        *DXAPIEndPoint
	StatusCode   int
	Description  string
	Headers      map[string]string
	DataTemplate []*DXAPIEndPointParameter
}

type DXAPIEndPointType int

type DXAPIEndPointWSCloseFunc func(aepr *DXAPIEndPointRequest)

type DXAPIEndPointWSMessageFunc func(aepr *DXAPIEndPointRequest, message []byte) (response []byte, err error)

type DXAPIEndPointWSOpenFunc func(aepr *DXAPIEndPointRequest) (err error)

type DXAPIEndPointWSPeriodicFunc func(aepr *DXAPIEndPointRequest) (err error)

type DXAPIEndPointWebSocketClient struct {
	Id   string
	Conn *websocket.Conn
	Send chan []byte
}

type DXAPIError struct {
	StatusCode int
	Code       string
	Operation  string
	Cause      error
	Next       string
}

type DXAPIManager struct {
	Context           context.Context
	Cancel            context.CancelFunc
	APIs              map[string]*DXAPI
	ErrorGroup        *errgroup.Group
	ErrorGroupContext context.Context
}

type DXAPIUser struct {
	Id               string
	Uid              string
	LoginId          string
	FullName         string
	OrganizationId   string
	OrganizationUid  string
	OrganizationName string
}

type DXAuditLogHandler func(ctx context.Context, oldAuditLogId int64, parameters *DXAPIAuditLogEntry) (newAuditLogId int64, err error)

type DXOpenAPIComponents struct {
	Schemas         *DXOpenAPIOrderedMap[*DXOpenAPISchema]         `json:"schemas,omitempty"`
	SecuritySchemes *DXOpenAPIOrderedMap[*DXOpenAPISecurityScheme] `json:"securitySchemes,omitempty"`
}

type DXOpenAPIDocument struct {
	OpenAPI    string                                   `json:"openapi"`
	Info       DXOpenAPIInfo                            `json:"info"`
	Paths      *DXOpenAPIOrderedMap[*DXOpenAPIPathItem] `json:"paths"`
	Components *DXOpenAPIComponents                     `json:"components,omitempty"`
	// Security is the top-level security requirement. Only one is ever emitted
	// here -- mutualTLS, and only when the API is actually served under
	// mode: mtls. See openAPISecurityForTLS.
	Security []DXOpenAPISecurityRequirement `json:"security,omitempty"`
	// WebSocketEndPoints is x-dxlib-websocket-endpoints. OpenAPI 3.1 describes
	// request/response operations and has no construct for a socket lifecycle,
	// so WebSocket endpoints are listed here rather than under paths, where a
	// reader would take them for ordinary GETs.
	WebSocketEndPoints *DXOpenAPIWebSocketEndPoints `json:"x-dxlib-websocket-endpoints,omitempty"`
}

type DXOpenAPIHeader struct {
	Description string           `json:"description,omitempty"`
	Required    bool             `json:"required,omitempty"`
	Schema      *DXOpenAPISchema `json:"schema,omitempty"`
}

type DXOpenAPIInfo struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description,omitempty"`
}

type DXOpenAPIMediaType struct {
	Schema *DXOpenAPISchema `json:"schema,omitempty"`
}

type DXOpenAPIOperation struct {
	OperationId string                                   `json:"operationId"`
	Summary     string                                   `json:"summary,omitempty"`
	Description string                                   `json:"description,omitempty"`
	Parameters  []*DXOpenAPIParameter                    `json:"parameters,omitempty"`
	RequestBody *DXOpenAPIRequestBody                    `json:"requestBody,omitempty"`
	Responses   *DXOpenAPIOrderedMap[*DXOpenAPIResponse] `json:"responses,omitempty"`

	// EndPointType is DXAPIEndPointType.String(), always written so that the
	// type is read off the document and never defaulted into place.
	EndPointType string `json:"x-dxlib-endpoint-type,omitempty"`
	// Privileges, RateLimitGroup and MaxContentLength are the endpoint fields
	// of the same names. Zero values are omitted and read back as zero.
	Privileges       []string `json:"x-dxlib-privileges,omitempty"`
	RateLimitGroup   string   `json:"x-dxlib-rate-limit-group,omitempty"`
	MaxContentLength int64    `json:"x-dxlib-max-content-length,omitempty"`
	// Middlewares names the middleware chain wrapping the handler, in the
	// order it runs, by Go function name. It is written for a reader of the
	// document and never bound: the chain is code, registered with the
	// handler, and that registration is what runs.
	Middlewares []string `json:"x-dxlib-middlewares,omitempty"`
	// IdempotencyKey names the header parameter that is the endpoint's
	// idempotency key. That parameter is the one in: header the dialect
	// carries; any other is refused.
	IdempotencyKey string `json:"x-dxlib-idempotency-key,omitempty"`
	// RequestContentType is written only where the request body cannot carry
	// it: a GET or DELETE declared with a content type, which dxlib ignores at
	// request time but which the declaration still holds.
	RequestContentType string `json:"x-dxlib-request-content-type,omitempty"`
	// Parameters is the declared parameter set for a body that is not the
	// parameters: application/octet-stream and text/plain, where the values
	// arrive in the X-Var header, and a POST with no content type. It is an
	// object schema, one property per parameter.
	ParametersSchema *DXOpenAPISchema `json:"x-dxlib-parameters,omitempty"`
}

type DXOpenAPIOrderedMap[V any] struct {
	// contains filtered or unexported fields
}

type DXOpenAPIParameter struct {
	Name        string           `json:"name"`
	In          string           `json:"in"`
	Description string           `json:"description,omitempty"`
	Required    bool             `json:"required,omitempty"`
	Schema      *DXOpenAPISchema `json:"schema"`
}

type DXOpenAPIPathItem struct {
	Summary     string              `json:"summary,omitempty"`
	Description string              `json:"description,omitempty"`
	Get         *DXOpenAPIOperation `json:"get,omitempty"`
	Put         *DXOpenAPIOperation `json:"put,omitempty"`
	Post        *DXOpenAPIOperation `json:"post,omitempty"`
	Delete      *DXOpenAPIOperation `json:"delete,omitempty"`
	Options     *DXOpenAPIOperation `json:"options,omitempty"`
	Head        *DXOpenAPIOperation `json:"head,omitempty"`
	Patch       *DXOpenAPIOperation `json:"patch,omitempty"`
	Trace       *DXOpenAPIOperation `json:"trace,omitempty"`
}

type DXOpenAPIRequestBody struct {
	Description string                                    `json:"description,omitempty"`
	Required    bool                                      `json:"required,omitempty"`
	Content     *DXOpenAPIOrderedMap[*DXOpenAPIMediaType] `json:"content"`
}

type DXOpenAPIResponse struct {
	Description string                                    `json:"description"`
	Headers     *DXOpenAPIOrderedMap[*DXOpenAPIHeader]    `json:"headers,omitempty"`
	Content     *DXOpenAPIOrderedMap[*DXOpenAPIMediaType] `json:"content,omitempty"`
	// Name is the key the endpoint gave this possibility in its
	// ResponsePossibilities map. OpenAPI keys responses by status code, so the
	// name travels beside it.
	Name string `json:"x-dxlib-response-name,omitempty"`
}

type DXOpenAPISchema struct {
	Ref                  string                                 `json:"$ref,omitempty"`
	Type                 DXOpenAPISchemaType                    `json:"type,omitempty"`
	Format               string                                 `json:"format,omitempty"`
	Title                string                                 `json:"title,omitempty"`
	Description          string                                 `json:"description,omitempty"`
	Properties           *DXOpenAPIOrderedMap[*DXOpenAPISchema] `json:"properties,omitempty"`
	Required             []string                               `json:"required,omitempty"`
	Items                *DXOpenAPISchema                       `json:"items,omitempty"`
	AdditionalProperties *DXOpenAPISchema                       `json:"additionalProperties,omitempty"`
	Enum                 []any                                  `json:"enum,omitempty"`
	Minimum              *float64                               `json:"minimum,omitempty"`
	ExclusiveMinimum     *float64                               `json:"exclusiveMinimum,omitempty"`
	MinLength            *int                                   `json:"minLength,omitempty"`
	Maximum              *float64                               `json:"maximum,omitempty"`
	ExclusiveMaximum     *float64                               `json:"exclusiveMaximum,omitempty"`
	MultipleOf           *float64                               `json:"multipleOf,omitempty"`
	MaxLength            *int                                   `json:"maxLength,omitempty"`
	Pattern              string                                 `json:"pattern,omitempty"`
	MinItems             *int                                   `json:"minItems,omitempty"`
	MaxItems             *int                                   `json:"maxItems,omitempty"`
	UniqueItems          bool                                   `json:"uniqueItems,omitempty"`
	Const                *any                                   `json:"const,omitempty"`
	// Default, ReadOnly and WriteOnly are annotations: carried, never
	// checked or applied. See DXAPIEndPointParameter.
	Default   *any `json:"default,omitempty"`
	ReadOnly  bool `json:"readOnly,omitempty"`
	WriteOnly bool `json:"writeOnly,omitempty"`
	// DXLibType is the exact dxlib parameter type. Several dxlib types share
	// one JSON type -- int64, int64p and id are all integer/int64 -- so the
	// JSON Schema alone cannot say which validator runs. With it present the
	// binder uses it exactly; without it the binder infers the closest dxlib
	// type from type and format, as OPENAPI.md tabulates.
	DXLibType string `json:"x-dxlib-type,omitempty"`
}

type DXOpenAPISchemaType []string

type DXOpenAPISecurityRequirement map[string][]string

type DXOpenAPISecurityScheme struct {
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
}

type DXOpenAPIWSHandler struct {
	OnOpen      DXAPIEndPointWSOpenFunc
	OnMessage   DXAPIEndPointWSMessageFunc
	OnClose     DXAPIEndPointWSCloseFunc
	OnPeriodic  DXAPIEndPointWSPeriodicFunc
	OnLoop      DXAPIEndPointExecuteFunc
	Middlewares []DXAPIEndPointExecuteFunc
}

type DXOpenAPIWebSocketEndPoint struct {
	OperationId    string   `json:"operationId"`
	Path           string   `json:"path"`
	Method         string   `json:"method"`
	Summary        string   `json:"summary,omitempty"`
	Description    string   `json:"description,omitempty"`
	Privileges     []string `json:"privileges,omitempty"`
	RateLimitGroup string   `json:"rateLimitGroup,omitempty"`
	// PeriodicInterval is a Go duration string ("5s"); empty means the
	// library default of thirty seconds.
	PeriodicInterval string `json:"periodicInterval,omitempty"`
	// Middlewares is x-dxlib-middlewares for a WebSocket endpoint, under the
	// unprefixed name this block uses for every field.
	Middlewares []string `json:"middlewares,omitempty"`
}

type DXOpenAPIWebSocketEndPoints struct {
	Description string                        `json:"description"`
	EndPoints   []*DXOpenAPIWebSocketEndPoint `json:"endpoints"`
}

type ErrUniqueFieldViolation struct {
	TableName string
	Fields    []string
	Values    utils.JSON
}