config

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Sep 17, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package config defines the verified runtime models and enum types for the hclapi engine.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseFieldType 

func ParseFieldType(raw string) (DataType, string, DataType, error)

ParseFieldType parses a field type string into its base DataType, optional SchemaRef, and optional ItemsType.

func ValidateFormat 

func ValidateFormat(raw string) error

ValidateFormat checks whether a format string is a recognized OpenAPI standard.

Types

type CompiledEndpoint 

type CompiledEndpoint struct {
	Method       string
	Path         string
	RoutePattern string
	OperationID  string
	Summary      string
	Tag          string
	Hidden       bool
	Request      RequestRules
	Pipeline     []Step
}

CompiledEndpoint is a flattened route binding method, path, and pipeline steps.

type Config 

type Config struct {
	Server      Server                `json:"server"`
	OpenAPI     OpenAPIMetadata       `json:"openapi"`
	Telemetry   Telemetry             `json:"telemetry"`
	Connections map[string]Connection `json:"connections"`
	Schemas     map[string]Schema     `json:"schemas"`
	Endpoints   []CompiledEndpoint    `json:"-"`
}

Config represents the evaluated, type-checked hclapi service configuration.

type Connection 

type Connection struct {
	Type   ConnectionType `json:"type"`
	Name   string         `json:"name"`
	Engine string         `json:"engine"`
	Source string         `json:"source,omitempty"`
	URL    string         `json:"url,omitempty"`
	Pool   *Pool          `json:"pool,omitempty"`
}

Connection represents an external database or cache pool.

type ConnectionType 

type ConnectionType string

ConnectionType defines the category of an external connection pool. 

const (
	// ConnectionTypeSQL identifies relational database connection pools.
	ConnectionTypeSQL ConnectionType = "sql"

	// ConnectionTypeValkey identifies Valkey key-value connection pools.
	ConnectionTypeValkey ConnectionType = "valkey"
)

func ParseConnectionType 

func ParseConnectionType(raw string) (ConnectionType, error)

ParseConnectionType validates that a string strictly matches an allowed ConnectionType.

type Contact 

type Contact struct {
	Name  string `hcl:"name,optional"  json:"name"`
	Email string `hcl:"email,optional" json:"email"`
	URL   string `hcl:"url,optional"   json:"url"`
}

Contact contains maintainer contact details for documentation specs.

type DataType 

type DataType string

DataType specifies primitive data types strictly adhering to OpenAPI 3.1. 

const (
	// DataTypeString represents textual data.
	DataTypeString DataType = "string"

	// DataTypeInteger represents whole numbers.
	DataTypeInteger DataType = "integer"

	// DataTypeNumber represents any numeric value, including floating-point numbers.
	DataTypeNumber DataType = "number"

	// DataTypeBoolean represents true or false values.
	DataTypeBoolean DataType = "boolean"

	// DataTypeArray represents an ordered sequence of elements.
	DataTypeArray DataType = "array"

	// DataTypeObject represents an unordered mapping of key-value pairs.
	DataTypeObject DataType = "object"
)

func ParseDataType 

func ParseDataType(raw string) (DataType, error)

ParseDataType validates that a type strictly adheres to OpenAPI 3.1 primitives.

type DocsRenderer 

type DocsRenderer string

DocsRenderer specifies the UI viewer technology to render. 

const (
	// DocsRendererScalar renders the Scalar interactive API reference portal.
	DocsRendererScalar DocsRenderer = "scalar"

	// DocsRendererSwagger renders the Swagger UI portal.
	DocsRendererSwagger DocsRenderer = "swagger"

	// DocsRendererElements renders the Stoplight Elements portal.
	DocsRendererElements DocsRenderer = "elements"

	// DocsRendererRedoc renders the Redoc documentation portal.
	DocsRendererRedoc DocsRenderer = "redoc"
)

func ParseDocsRenderer 

func ParseDocsRenderer(raw string) (DocsRenderer, error)

ParseDocsRenderer validates that a renderer strictly matches an allowed DocsRenderer.

type DocsStep 

type DocsStep struct {
	Renderer DocsRenderer
	SpecURL  string
	Title    string
	Template string
}

DocsStep configures rendering of an interactive API documentation portal.

type Field 

type Field struct {
	Name        string   `json:"name"`
	Type        DataType `json:"type"`                 // Primary OpenAPI type (string, integer, array, object)
	SchemaRef   string   `json:"schema_ref,omitempty"` // Target schema name if type is a custom schema or []schema
	ItemsType   DataType `json:"items_type,omitempty"` // Primitive items type if type is []string, []int, etc.
	Format      Format   `json:"format,omitempty"`     // Strict OpenAPI format
	Required    bool     `json:"required,omitempty"`
	Default     any      `json:"default,omitempty"`
	Description string   `json:"description,omitempty"`
	Min         *float64 `json:"min,omitempty"`
	Max         *float64 `json:"max,omitempty"`
	MinLength   *int     `json:"min_length,omitempty"`
	MaxLength   *int     `json:"max_length,omitempty"`
	Enum        []string `json:"enum,omitempty"`
}

Field defines validation rules and OpenAPI schema attributes strictly adhering to OpenAPI 3.1.

type Format 

type Format string

Format defines standard semantic string formats recognized in OpenAPI 3.1. 

const (
	// FormatEmail defines RFC 5322 standard email addresses.
	FormatEmail Format = "email"

	// FormatUUID defines RFC 4122 universally unique identifiers.
	FormatUUID Format = "uuid"

	// FormatDateTime defines RFC 3339 date-time timestamps.
	FormatDateTime Format = "date-time"

	// FormatDate defines full-date representations formatted as YYYY-MM-DD.
	FormatDate Format = "date"

	// FormatURI defines full RFC 3986 universal resource identifiers.
	FormatURI Format = "uri"

	// FormatIPv4 defines standard dot-decimal IPv4 addresses.
	FormatIPv4 Format = "ipv4"

	// FormatIPv6 defines standard colon-separated IPv6 addresses.
	FormatIPv6 Format = "ipv6"

	// FormatHostname defines RFC 1123 compliant domain names.
	FormatHostname Format = "hostname"
)

type GoStep 

type GoStep struct {
	Use      string
	ArgsExpr hcl.Expression
}

GoStep invokes a registered native Go callback.

type HTTPStep 

type HTTPStep struct {
	Method   string
	URLExpr  hcl.Expression
	Headers  map[string]string
	BodyExpr hcl.Expression
	Timeout  scalar.Duration
}

HTTPStep makes outbound HTTP requests to external services.

type License 

type License struct {
	Name string `hcl:"name"         json:"name"`
	URL  string `hcl:"url,optional" json:"url"`
}

License contains licensing information for the exposed API.

type Logging 

type Logging struct {
	Level  string   `hcl:"level,optional"  json:"level"`
	Format string   `hcl:"format,optional" json:"format"`
	Redact []string `hcl:"redact,optional" json:"redact"`
}

Logging sets log level, output formatting, and sensitive field redaction paths.

type OpenAPIMetadata 

type OpenAPIMetadata struct {
	Title       string          `hcl:"title,optional"       json:"title"`
	Version     string          `hcl:"version,optional"     json:"version"`
	Description string          `hcl:"description,optional" json:"description"`
	Servers     []OpenAPIServer `                           json:"servers"`
	Tags        []OpenAPITag    `                           json:"tags"`
	Contact     *Contact        `                           json:"contact,omitempty"`
	License     *License        `                           json:"license,omitempty"`
}

OpenAPIMetadata defines global documentation metadata according to OpenAPI 3.1.

type OpenAPIServer 

type OpenAPIServer struct {
	URL         string `hcl:"url"                  json:"url"`
	Description string `hcl:"description,optional" json:"description"`
}

OpenAPIServer defines a target deployment server.

type OpenAPITag 

type OpenAPITag struct {
	Name        string `hcl:"name"                 json:"name"`
	Description string `hcl:"description,optional" json:"description"`
}

OpenAPITag categorizes endpoints in interactive documentation portals.

type Pool 

type Pool struct {
	MaxOpen int `hcl:"max_open,optional" json:"max_open"`
	MaxIdle int `hcl:"max_idle,optional" json:"max_idle"`
}

Pool sets database connection pool bounds.

type RequestRules 

type RequestRules struct {
	Path    map[string]Field `json:"path"`
	Query   map[string]Field `json:"query"`
	Headers map[string]Field `json:"headers"`
	Body    map[string]Field `json:"body"`
	BodyRef string           `json:"body_ref,omitempty"`
}

RequestRules defines ingress validation constraints across the 4 request coordinates.

func (RequestRules) HasRules 

func (r RequestRules) HasRules() bool

HasRules reports whether any coordinate defines validation constraints.

type RespondStep 

type RespondStep struct {
	Status    int
	SchemaRef string
	Headers   map[string]string
	BodyExpr  hcl.Expression
}

RespondStep serializes an HTTP response and terminates pipeline execution.

type SQLCatch 

type SQLCatch struct {
	Code     string
	Status   int
	BodyExpr hcl.Expression
}

SQLCatch configures HTTP problem responses for specific database error codes.

type SQLEngine 

type SQLEngine string

SQLEngine specifies the canonical relational database engine. 

const (
	// SQLEnginePostgres identifies PostgreSQL databases.
	SQLEnginePostgres SQLEngine = "postgres"

	// SQLEngineMySQL identifies MySQL and MariaDB databases.
	SQLEngineMySQL SQLEngine = "mysql"

	// SQLEngineSQLite identifies SQLite embedded databases.
	SQLEngineSQLite SQLEngine = "sqlite"

	// SQLEngineSQLServer identifies Microsoft SQL Server databases.
	SQLEngineSQLServer SQLEngine = "sqlserver"
)

func ParseSQLEngine 

func ParseSQLEngine(raw string) (SQLEngine, error)

ParseSQLEngine validates that a string strictly matches an allowed canonical SQLEngine.

type SQLStep 

type SQLStep struct {
	Connection string
	Query      string
	ArgsExpr   hcl.Expression
	Catches    []SQLCatch
}

SQLStep models relational database queries.

type Schema 

type Schema struct {
	Name        string           `json:"name"`
	Description string           `json:"description,omitempty"`
	Fields      map[string]Field `json:"fields"`
}

Schema defines a reusable domain data model.

type Server 

type Server struct {
	Host         string          `hcl:"host,optional"          json:"host"`
	Port         int             `hcl:"port,optional"          json:"port"`
	ReadTimeout  scalar.Duration `hcl:"read_timeout,optional"  json:"read_timeout"`
	WriteTimeout scalar.Duration `hcl:"write_timeout,optional" json:"write_timeout"`
	MaxBodySize  scalar.ByteSize `hcl:"max_body_size,optional" json:"max_body_size"`
}

Server holds listener host/port boundaries and timeout limits.

type SpecFormat 

type SpecFormat string

SpecFormat specifies the serialization encoding for OpenAPI specifications. 

const (
	// SpecFormatJSON serializes specifications as indented JSON.
	SpecFormatJSON SpecFormat = "json"

	// SpecFormatYAML serializes specifications as YAML.
	SpecFormatYAML SpecFormat = "yaml"
)

func ParseSpecFormat 

func ParseSpecFormat(raw string) (SpecFormat, error)

ParseSpecFormat validates that a format strictly matches an allowed SpecFormat.

type SpecStep 

type SpecStep struct {
	Format SpecFormat
}

SpecStep serves the compiled OpenAPI 3.1 specification document.

type StarlarkStep 

type StarlarkStep struct {
	Source string
}

StarlarkStep executes an embedded Starlark script.

type Step 

type Step struct {
	Type     StepType `json:"type"`
	Name     string
	WhenExpr hcl.Expression

	SQL      *SQLStep
	Valkey   *ValkeyStep
	Respond  *RespondStep
	Docs     *DocsStep
	Spec     *SpecStep
	Go       *GoStep
	Starlark *StarlarkStep
	HTTP     *HTTPStep
}

Step represents a polymorphic pipeline execution step.

type StepType 

type StepType string

StepType defines the exact execution category of a pipeline step. 

const (
	// StepTypeSQL executes parameterized relational database statements.
	StepTypeSQL StepType = "sql"

	// StepTypeValkey executes caching operations against Valkey instances.
	StepTypeValkey StepType = "valkey"

	// StepTypeHTTP performs outbound HTTP requests to external services.
	StepTypeHTTP StepType = "http"

	// StepTypeStarlark executes sandboxed Starlark scripts.
	StepTypeStarlark StepType = "starlark"

	// StepTypeGo invokes a registered native Go callback function.
	StepTypeGo StepType = "go"

	// StepTypeRespond serializes an HTTP response and terminates pipeline execution.
	StepTypeRespond StepType = "respond"

	// StepTypeDocs renders an interactive API documentation viewer.
	StepTypeDocs StepType = "docs"

	// StepTypeSpec serves compiled OpenAPI specification documents.
	StepTypeSpec StepType = "spec"
)

func ParseStepType 

func ParseStepType(raw string) (StepType, error)

ParseStepType validates that a string strictly matches an allowed StepType.

type Telemetry 

type Telemetry struct {
	ServiceName string  `hcl:"service_name,optional" json:"service_name"`
	Logging     Logging `hcl:"logging,block"         json:"logging"`
}

Telemetry configures distributed tracing and operational logging.

type ValkeyOp 

type ValkeyOp string

ValkeyOp defines the caching operation to perform. 

const (
	// ValkeyOpGet retrieves a string value by key.
	ValkeyOpGet ValkeyOp = "get"

	// ValkeyOpSet sets a string value with an optional expiration.
	ValkeyOpSet ValkeyOp = "set"

	// ValkeyOpDel removes a key from the store.
	ValkeyOpDel ValkeyOp = "del"
)

func ParseValkeyOp 

func ParseValkeyOp(raw string) (ValkeyOp, error)

ParseValkeyOp validates that an operation string strictly matches an allowed ValkeyOp.

type ValkeyStep 

type ValkeyStep struct {
	Connection string
	Op         ValkeyOp
	KeyExpr    hcl.Expression
	ValExpr    hcl.Expression
	TTL        time.Duration
}

ValkeyStep executes key-value caching operations against Valkey.

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.