httpapi

package
v0.511.0 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

README

HTTP Interface Module

HTTP exposes DeltaScope audit and metadata-aware review capabilities as a JSON service.

Files

File Responsibility
audit_metadata.go Executes one HTTP audit request through offline or registry metadata-aware flows and preserves adapter context plus partial public results when an audit returns diagnostics and an error
audit_metadata_test.go Verifies HTTP metadata-aware execution wiring, additive context, and direct metadata client lifecycle handling
audit_impact_postgresql_tag_test.go Verifies PostgreSQL offline primary-key equality impact in HTTP JSON output
audit_dml_table_existence_test.go Verifies registry-backed MySQL/TiDB INSERT/UPDATE/DELETE missing-target findings and stable HTTP result shape
audit_offline_existence_test.go Locks offline ALTER DROP COLUMN HTTP JSON context.note / context.unproven and capabilities context_fields
handler.go Binds Gin HTTP requests to public APIs, emits diagnostic error envelopes that retain the full partial audit result beside the bounded transport error, and maps MCP connection_ref to field-level invalid_request instead of opaque invalid_json
handler_unsupported_diagnostics_evidence_test.go Verifies HTTP parser diagnostics preserve the review-floored partial result, valid statements/findings, locations, context, error status, and no-leak boundaries
handler_unsupported_verdict_floor_postgresql_tag_test.go Verifies HTTP PostgreSQL SELECT 1 keeps non-success status and serializes the review-floored unsupported result
handler_test.go Verifies HTTP request binding, error mapping, JSON response shape without CLI-only fail_on_triggered, metadata-aware omission of offline existence caveats, and field-level rejection of MCP connection_ref
rule_catalog.go Builds HTTP rule-list, rule-detail, and capability payloads from the shipped catalog metadata, including note / unproven on context_fields and stable online identity/authentication error codes
query_access.go Handles HTTP query access analysis requests, canonicalizes named MySQL/TiDB database/schema aliases with the missing default qualifier, keeps request-only defaults out of catalog selection, rejects conflicting hints before open, preserves registry/authorization/connection/error/log ownership, maps bounded PostgreSQL PG17 identity and database-authentication boundaries, and routes online analysis through attachOnlineQueryAccessSession (reuses OpenSession identity; no second probe)
query_access_test.go Verifies request binding, MySQL/TiDB database/schema/default-schema aliases and conflicts, PostgreSQL database/schema preservation and PG17 boundary, response shape, unified online routing, bounded failures, zero-open authorization paths, and close ownership
query_access_issue35_postgresql_tag_test.go Verifies CLI and HTTP share the normalized PostgreSQL read_only/admissible state and reason codes
query_access_unified_entry_test.go Structurally verifies handleQueryAccessOnline contains no product inspection or dialect-specific Query Access constructor/analysis calls, uses both unified SDK entry symbols, and reuses Observed Server Identity
query_access_postgresql_online_recording_test.go Focused recording-driver proof that the PostgreSQL online HTTP connection_id path delegates through a pinned session, closes once, maps bounded catalog failures, and never executes submitted SQL, EXPLAIN, or prepare operations
query_access_e2e_mixed_literal_test.go Docker-backed HTTP smoke for admitted and fail-closed MySQL 8.4 and TiDB 8.5 routes, including unqualified seeded-table schema-only resolution through named connections, with response and access-log scans that keep registered DSN credential markers out of admitted paths, plus HTTP default/offline and bounded credential-failure no-leak coverage
query_access_probe_boundary_no_leak_test.go No-leak regression for the MySQL/TiDB builtin-identity probe boundary on the HTTP surface: asserts injected markers, identity facts, candidates, session/context, manifest, raw SQL, and severity are absent from the response body (including the error boundary)
query_access_postgresql_no_leak_test.go PostgreSQL 17 integration no-leak coverage for online COUNT(1), excluded shapes, missing connection_id, and unauthorized HTTP paths
server.go Assembles the HTTP handler and long-running server wiring

Exports

  • NewHandler(configPath, version, opts ...HandlerOption) (http.Handler, error)
  • WithAuthConfig(AuthConfig) HandlerOption
  • WithMiddlewareConfig(MiddlewareConfig) HandlerOption
  • WithAuditFunc(func(context.Context, deltascope.Request) (deltascope.Result, error)) HandlerOption
  • WithMetadataConfig(MetadataConfig) HandlerOption
  • NewServer(addr, configPath, version, opts ...HandlerOption)

Notes

  • Online Query Access keeps registry lookup, authorization, TLS/credential resolution, cancellation, connection close, HTTP errors, request IDs, and access logs in HTTP, canonicalizes named MySQL/TiDB database/schema aliases with the default qualifier and bounded conflict rejection, then passes the caller-owned pinned connection to the opaque unified SDK session without inspecting observed product or constraining the analysis request dialect. A reachable PostgreSQL identity outside PG17 returns 502 identity_error with the fixed bounded requirement message; database authentication failure returns 502 authentication_failed; both are advertised by /v1/capabilities.
  • Query Access semantic breadth and detailed probe tests live in the unified SDK suite; this module retains only HTTP-owned transport, registry, authorization, sink, lifecycle, and real-route evidence.
  • The HTTP layer is adapter-only: it reuses the shared public audit API and metadata-preparation helpers instead of reimplementing dialect or schema logic.
  • Routing uses Gin while keeping the public JSON API contract unchanged.
  • API-key auth is optional and configured through adapter options.
  • Rate limiting is optional and supports api-key or ip bucketing.
  • /metrics is exposed in Prometheus format by default and can be disabled via middleware config.
  • Default middleware chain is request-id -> recovery -> timeout -> metrics -> auth -> rate-limit -> access log.
  • Config hot-reload is achieved by re-reading the configured policy path on each audit request, so file updates take effect without restarting the server.
  • Current scope supports offline and metadata-aware audit, HTTP-native rule discovery, capability discovery, and query access analysis.
  • Responses preserve the public DeltaScope result body and add a context block describing mode, dialect/schema provenance, and metadata source. Parser-error responses use the same top-level result/context shape plus an error object, retaining valid statement findings and the shared partial-result review floor while still returning a non-success status.
  • Direct connection input accepts connect_timeout (duration string like 5s); empty/omitted/0s falls back to runtime config default, invalid/negative values return 400.

Dependencies

  • Upstream: cmd/deltascope-server
  • Downstream: pkg/deltascope, internal/application/policy, internal/application/queryaccess, internal/domain/rule/catalog, internal/interfaces/metadata

Update Rule

  • If members/interfaces/dependencies change, update this file in same change.

Documentation

Overview

Package httpapi exposes the HTTP adapter for DeltaScope. input: parsed HTTP audit requests, shared metadata-preparation helpers, and public audit execution functions output: additive HTTP audit context including offline existence caveats plus offline or registry-based metadata-aware audit execution results pos: HTTP adapter glue between request-scoped metadata inputs and the public DeltaScope audit API note: if this file changes, update this header and module README.md.

Package httpapi exposes the HTTP adapter for DeltaScope. input: HTTP requests carrying SQL audit payloads plus service-level config/version wiring output: JSON audit, partial audit error results, named invalid_request envelopes for rejected connection/connection_ref fields, rule-catalog, capability, health, readiness, version, and structured access log lines pos: interface adapter between net/http and the public DeltaScope audit API note: if this file changes, update this header and module README.md.

Package httpapi exposes the HTTP adapter for DeltaScope. input: query-access JSON requests, catalog/schema hints, authorized runtime connection configuration, and the unified public online query access API output: bounded offline or alias-bound identity-routed online query-access JSON responses with stable identity error mapping and unchanged logging contracts pos: HTTP query-access adapter above offline analysis and the opaque unified online session boundary note: if this file changes, update this header and module README.md.

Package httpapi exposes the HTTP adapter for DeltaScope. input: HTTP rule-discovery requests plus shipped catalog and capability metadata output: JSON rule-list, rule-detail, and capability payloads including offline existence context_fields and stable online identity errors for the HTTP adapter pos: HTTP discovery helpers above the domain rule catalog and shared JSON writers note: if this file changes, update this header and module README.md.

Package httpapi exposes the HTTP adapter for DeltaScope. input: listen addresses plus service-level config/version wiring output: ready-to-run HTTP server instances for the JSON audit service pos: long-running net/http server assembly for the HTTP interface milestone note: if this file changes, update this header and module README.md.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewHandler 

func NewHandler(configPath, version string, opts ...HandlerOption) (http.Handler, error)

NewHandler returns the JSON HTTP adapter for DeltaScope.

func NewServer 

func NewServer(addr, configPath, version string, opts ...HandlerOption) (*http.Server, error)

NewServer builds the DeltaScope HTTP service.

func PrincipalIDFromContext added in v0.420.0 

func PrincipalIDFromContext(ctx context.Context) string

PrincipalIDFromContext returns the authenticated principal ID from the request context. Returns empty string when auth is disabled or the request is unauthenticated.

Types

type AuthConfig added in v0.10.0 

type AuthConfig struct {
	Enabled    bool
	Keys       []string
	AllowPaths []string
}

AuthConfig controls API-key authentication on the HTTP adapter.

type HandlerOption added in v0.10.0 

type HandlerOption func(*handlerOptions)

HandlerOption configures NewHandler behavior.

func WithAuditFunc added in v0.10.0 

func WithAuditFunc(fn func(context.Context, deltascope.Request) (deltascope.Result, error)) HandlerOption

WithAuditFunc overrides the audit execution function (primarily for tests).

func WithAuthConfig added in v0.10.0 

func WithAuthConfig(cfg AuthConfig) HandlerOption

WithAuthConfig enables API-key authentication on selected routes.

func WithMetadataConfig added in v0.63.0 

func WithMetadataConfig(cfg MetadataConfig) HandlerOption

WithMetadataConfig sets runtime-level metadata defaults for the HTTP adapter.

func WithMiddlewareConfig added in v0.10.0 

func WithMiddlewareConfig(cfg MiddlewareConfig) HandlerOption

WithMiddlewareConfig overrides default middleware settings.

func WithRegistry added in v0.420.0 

func WithRegistry(reg *runtimeconfig.Registry) HandlerOption

func WithSlogLogger added in v0.62.0 

func WithSlogLogger(sl *slog.Logger) HandlerOption

WithSlogLogger sets the structured logger. The slog.Logger is bridged to a *log.Logger for use by existing recovery and access-log middleware. If sl is nil the option is a no-op and the default log.Default() logger is used.

type MetadataConfig added in v0.63.0 

type MetadataConfig struct {
	ConnectTimeout time.Duration
}

MetadataConfig carries runtime-level metadata defaults for the HTTP adapter.

type MiddlewareConfig added in v0.10.0 

type MiddlewareConfig struct {
	RequestTimeout time.Duration
	Logger         *log.Logger
	RateLimit      RateLimitConfig
	MetricsEnabled *bool
	TrustedProxies []string
}

MiddlewareConfig controls default middleware behavior.

type RateLimitConfig added in v0.10.0 

type RateLimitConfig struct {
	Enabled    bool
	RPS        float64
	Burst      int
	KeyBy      string
	AllowPaths []string
}

RateLimitConfig controls per-key request throttling.

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.