manifest

type Args ¶ added in v0.2.1

type Args map[string]any

Args represents evaluated key-value arguments supplied to a native Go step handler.

func (a Args) Bind(dst any) error

func (a Args) Get[T any](key string) (T, bool)

func (a Args) GetOr[T any](key string, fallback T) T

func (a Args) Has(key string) bool

func (a Args) Slice[T any](key string) []T

type ByteSize ¶ added in v0.2.1

type ByteSize int64

ByteSize represents a quantity of bytes.

func ParseByteSize(raw string) (ByteSize, error)

func (b ByteSize) Bytes() int64

func (b ByteSize) String() string

type Connection ¶

type Connection struct {
	Type    string
	Name    string
	Engine  string
	Source  string
	URL     string
	MaxOpen int
	MaxIdle int
}

Connection defines external database connection pools and cache instances.

type Contact ¶ added in v0.2.1

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

Contact contains API maintainer details exported in the specification info block.

type DataType ¶ added in v0.2.1

type DataType string

DataType represents an OpenAPI 3.1 primitive or collection type.

const (
	TypeString  DataType = "string"
	TypeInteger DataType = "integer"
	TypeNumber  DataType = "number"
	TypeBoolean DataType = "boolean"
	TypeObject  DataType = "object"
	TypeArray   DataType = "array"
)

func (dt DataType) IsValid() bool

type Duration ¶ added in v0.2.1

type Duration time.Duration

Duration wraps time.Duration to represent human-configured intervals.

func ParseDuration(raw string) (Duration, error)

func (d Duration) Duration() time.Duration

func (d Duration) String() string

type Expr ¶ added in v0.2.1

type Expr interface {
	Eval(scope Scope) (any, error)
	EvalBool(scope Scope) (bool, error)
	EvalMap(scope Scope) (map[string]any, error)
	String() string
	Raw() hcl.Expression
}

Expr represents a compiled HCL expression ready for evaluation against a Scope.

func NewExpr(raw hcl.Expression, funcs map[string]function.Function) Expr

type Field ¶

type Field struct {
	Name        string
	Type        TypeSpec
	Required    bool
	Format      Format
	Default     any
	Description string
	Min         *float64
	Max         *float64
	MinLength   *int
	MaxLength   *int
	Enum        []string
}

Field specifies validation constraints and documentation metadata for a model attribute.

type Format ¶ added in v0.2.1

type Format string

Format defines semantic string constraints specified by OpenAPI.

const (
	FormatEmail    Format = "email"
	FormatUUID     Format = "uuid"
	FormatURI      Format = "uri"
	FormatDateTime Format = "date-time"
	FormatDate     Format = "date"
	FormatIPv4     Format = "ipv4"
	FormatIPv6     Format = "ipv6"
	FormatHostname Format = "hostname"
)

type GoHandler ¶ added in v0.2.1

type GoHandler func(ctx context.Context, req *GoRequest) (any, error)

GoHandler defines the function signature for custom Go step callbacks registered on the runtime.

type GoRequest ¶ added in v0.2.1

type GoRequest struct {
	Name    string
	Args    Args
	Request *http.Request
}

GoRequest encapsulates the input arguments and active HTTP request passed to a GoHandler.

type IgnoreRules ¶ added in v0.2.0

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

IgnoreRules holds compiled ignore patterns loaded from a .hclapiignore file.

func LoadIgnoreRules(rootDir string) (*IgnoreRules, error)

func (ir *IgnoreRules) Matches(relPath string, isDir bool) bool

type License ¶ added in v0.2.1

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

License describes legal licensing terms for the exposed API contract.

type Manifest ¶ added in v0.1.3

type Manifest struct {
	Server      Server
	OpenAPI     OpenAPI
	Telemetry   Telemetry
	Connections map[string]Connection
	Schemas     map[string]Schema
	Routes      []Route
}

Manifest represents the compiled, validated AST for an entire API service.

func Load(patterns ...string) (*Manifest, error)

func Parse(source string) (*Manifest, error)

func (m *Manifest) Validate() error

type OpenAPI ¶ added in v0.2.1

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

OpenAPI holds document metadata exported into OpenAPI 3.1 specifications.

type OpenAPIServer ¶

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

OpenAPIServer defines a deployment origin in the generated specification.

type OpenAPITag ¶

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

OpenAPITag groups operations inside interactive documentation portals.

type Parser ¶ added in v0.2.1

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

Parser coordinates file discovery, HCL parsing, and AST compilation using a configurable StepRegistry.

func NewParser(registry *StepRegistry) *Parser

func (p *Parser) Load(patterns ...string) (*Manifest, error)

func (p *Parser) Parse(source string) (*Manifest, error)

type RecordSeq ¶ added in v0.2.1

type RecordSeq iter.Seq2[any, error]

RecordSeq defines the standard Go iterator yielding record items and potential errors.

type Request ¶ added in v0.2.1

type Request struct {
	Path    map[string]Field
	Query   map[string]Field
	Headers map[string]Field
	Body    map[string]Field
	BodyRef string
}

Request defines validation constraints across incoming HTTP request coordinates.

func (r *Request) HasRules() bool

type Route ¶ added in v0.2.1

type Route struct {
	Method  string
	Path    string
	Summary string
	Tag     string
	Hidden  bool
	Request *Request
	Steps   []Step
}

Route binds an HTTP method and URL pattern to an ordered pipeline of steps.

func (r Route) HasTerminalStep() bool

func (r Route) Pattern() string

type SQLCatch ¶ added in v0.2.1

type SQLCatch struct {
	Code       string
	Constraint string
	Match      string
	Status     int
	Body       Expr
}

SQLCatch specifies interception criteria for database driver errors.

type Schema ¶

type Schema struct {
	Name        string
	Description string
	Fields      map[string]Field
}

Schema represents a reusable domain model for payload validation and egress filtering.

type Scope ¶ added in v0.2.1

type Scope struct {
	Request map[string]any
	Steps   map[string]any
	Headers map[string]string
	Now     time.Time
}

Scope encapsulates the runtime execution state supplied to an Expr during evaluation.

type Server ¶

type Server struct {
	Host         string
	Port         int
	ReadTimeout  Duration
	WriteTimeout Duration
	MaxBodySize  ByteSize
}

Server defines listener addresses, transport limits, and network timeouts.

type Step ¶ added in v0.2.1

type Step interface {
	StepName() string
	StepWhen() Expr
	IsTerminal() bool
}

Step defines the minimal AST node contract for a route task.

type StepDecoder ¶ added in v0.2.1

type StepDecoder func(name string, body hcl.Body, evalCtx *hcl.EvalContext, funcs map[string]function.Function) (Step, error)

StepDecoder decodes an HCL block into a concrete Step implementation.

type StepDocs ¶ added in v0.2.1

type StepDocs struct {
	Renderer string
	SpecURL  string
	Title    string
	Template string
	When     Expr
}

StepDocs renders and streams an interactive API documentation portal.

It delegates template execution to docs.Render using precompiled, embedded HTML viewer templates (Scalar, Swagger UI, Redoc, or Stoplight Elements), or an optional user-defined template file on disk.

Upon execution, it sets the Content-Type header to "text/html; charset=utf-8", flushes the compiled HTML bytes, and halts pipeline progression by returning ErrPipelineHalted.

func (d *StepDocs) ExecuteStep(ctx context.Context, ec StepExecutionContext) (any, error)

func (d *StepDocs) IsTerminal() bool

func (d *StepDocs) StepName() string

func (d *StepDocs) StepWhen() Expr

func (d *StepDocs) ValidateStep(m *Manifest) error

type StepExecutionContext ¶ added in v0.2.1

type StepExecutionContext interface {
	SQL(name string) (*sql.DB, error)
	Valkey(name string) (valkey.Client, error)
	GoHandler(name string) (GoHandler, error)
	HTTPClient() *http.Client
	ResponseWriter() http.ResponseWriter
	ResponseController() *http.ResponseController
	OpenAPISpec(format string) ([]byte, string, error)
	Scope() Scope
	Schemas() map[string]Schema
}

StepExecutionContext supplies runtime dependencies and request state to steps during execution.

type StepExecutor ¶ added in v0.2.1

type StepExecutor interface {
	ExecuteStep(ctx context.Context, ec StepExecutionContext) (any, error)
}

StepExecutor is implemented by steps that execute runtime request logic.

type StepGo ¶ added in v0.2.1

type StepGo struct {
	Name string
	Use  string
	Args Expr
	When Expr
}

StepGo invokes a custom Go callback function registered on the runtime engine.

func (g *StepGo) ExecuteStep(ctx context.Context, ec StepExecutionContext) (res any, err error)

func (g *StepGo) IsTerminal() bool

func (g *StepGo) StepName() string

func (g *StepGo) StepWhen() Expr

func (g *StepGo) ValidateStep(m *Manifest) error

type StepHTTP ¶ added in v0.2.1

type StepHTTP struct {
	Name    string
	Method  string
	URL     Expr
	Body    Expr
	When    Expr
	Timeout Duration
	Headers map[string]string
	Stream  bool
}

StepHTTP makes outbound HTTP calls to external APIs.

In standard execution, response bodies up to 10MB are buffered, automatically parsed as JSON if applicable, and published to context as steps.<name>.status and steps.<name>.body. When Stream is true, buffering is skipped and the live socket is exported as an io.ReadCloser under steps.<name>.stream.

func (h *StepHTTP) ExecuteStep(ctx context.Context, ec StepExecutionContext) (any, error)

func (h *StepHTTP) IsTerminal() bool

func (h *StepHTTP) StepName() string

func (h *StepHTTP) StepWhen() Expr

func (h *StepHTTP) ValidateStep(m *Manifest) error

type StepRegistry ¶ added in v0.2.1

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

StepRegistry manages step decoders and generates dynamic HCL block schemas without global state.

func DefaultStepRegistry() *StepRegistry

func NewStepRegistry() *StepRegistry

func (r *StepRegistry) BlockHeaderSchemas() []hcl.BlockHeaderSchema

func (r *StepRegistry) Decode(block *hcl.Block, evalCtx *hcl.EvalContext, funcs map[string]function.Function) (Step, error)

func (r *StepRegistry) Register(keyword string, labelNames []string, decoder StepDecoder)

type StepRespond ¶ added in v0.2.1

type StepRespond struct {
	Status       int
	Headers      map[string]string
	When         Expr
	Body         Expr
	Schema       *TypeSpec
	InlineFields map[string]Field
}

StepRespond terminates pipeline execution, serializes the response payload, applies schema-based egress field masking, and streams the HTTP response to the client.

A respond step may declare a contract using an explicit named TypeSpec reference via Schema, an explicit inline schema block via InlineFields, or omit both to allow the compiler to statically infer the response shape directly from the Body expression.

func (r *StepRespond) ExecuteStep(ctx context.Context, ec StepExecutionContext) (any, error)

func (r *StepRespond) IsTerminal() bool

func (r *StepRespond) StepName() string

func (r *StepRespond) StepWhen() Expr

func (r *StepRespond) ValidateStep(m *Manifest) error

type StepSQL ¶ added in v0.2.1

type StepSQL struct {
	Name       string
	Connection string
	Query      string
	Args       Expr
	When       Expr
	Stream     bool
	Catches    []SQLCatch
	// contains filtered or unexported fields
}

StepSQL executes parameterized relational database queries against configured pools.

func (s *StepSQL) ExecuteStep(ctx context.Context, ec StepExecutionContext) (any, error)

func (s *StepSQL) IsTerminal() bool

func (s *StepSQL) StepName() string

func (s *StepSQL) StepWhen() Expr

func (s *StepSQL) ValidateStep(m *Manifest) error

type StepSpec ¶ added in v0.2.1

type StepSpec struct {
	Format string
	When   Expr
}

StepSpec serves the compiled OpenAPI specification in JSON or YAML format with ETag caching.

When incoming requests include a matching If-None-Match header, StepSpec returns HTTP 304 Not Modified without re-transmitting the document payload.

func (s *StepSpec) ExecuteStep(ctx context.Context, ec StepExecutionContext) (any, error)

func (s *StepSpec) IsTerminal() bool

func (s *StepSpec) StepName() string

func (s *StepSpec) StepWhen() Expr

func (s *StepSpec) ValidateStep(m *Manifest) error

type StepStarlark ¶ added in v0.2.1

type StepStarlark struct {
	Name   string
	Source string
	When   Expr
	// contains filtered or unexported fields
}

StepStarlark executes a sandboxed, deterministic Starlark (Python dialect) script for in-memory payload transformation, field enrichment, and filtering.

Scripts run in a hermetic runtime without access to the host filesystem, network, or environment variables. Execution is bounded by an instruction budget of 100,000 steps to guarantee termination and prevent runaway loops or unbounded recursion.

The script must declare an entrypoint function with the signature:

def execute(ctx):
    ...
    return result

The return value is unmarshaled into native Go types and published to the request scope as steps.<name>.result.

func (s *StepStarlark) ExecuteStep(ctx context.Context, ec StepExecutionContext) (any, error)

func (s *StepStarlark) IsTerminal() bool

func (s *StepStarlark) StepName() string

func (s *StepStarlark) StepWhen() Expr

func (s *StepStarlark) ValidateStep(m *Manifest) error

type StepStream ¶ added in v0.2.1

type StepStream struct {
	Format      string
	Source      Expr
	Event       string
	Heartbeat   Duration
	Retry       Duration
	FlushEvery  int
	Headers     map[string]string
	ContentType string
	Schema      *TypeSpec
	When        Expr
}

StepStream consumes a data stream and flushes items according to the declared protocol.

func (s *StepStream) ExecuteStep(ctx context.Context, ec StepExecutionContext) (any, error)

func (s *StepStream) IsTerminal() bool

func (s *StepStream) StepName() string

func (s *StepStream) StepWhen() Expr

func (s *StepStream) ValidateStep(m *Manifest) error

type StepValidator ¶ added in v0.2.1

type StepValidator interface {
	ValidateStep(m *Manifest) error
}

StepValidator is an optional interface implemented by AST step definitions that require semantic verification against the compiled manifest topology.

type StepValkey ¶ added in v0.2.1

type StepValkey struct {
	Name       string
	Connection string
	Op         string
	Key        Expr
	Value      Expr
	Channel    Expr
	TTL        Duration
	When       Expr
}

StepValkey executes caching commands or Pub/Sub subscriptions against Valkey or Redis.

Key-value commands ("get", "set", "del") publish execution metadata to context:

• "get": sets steps.<name>.found (bool) and steps.<name>.value (unmarshaled JSON or string). A cache miss doesn't return an error; it sets found = false and value = nil.
• "set": serializes the payload, sets expiration if configured, and sets steps.<name>.success = true.
• "del": removes the key and sets steps.<name>.success = true.

The "subscribe" operation produces a continuous RecordSeq iterator under steps.<name>.stream, allowing live messages to be piped directly into a terminal StepStream (e.g. SSE).

func (v *StepValkey) ExecuteStep(ctx context.Context, ec StepExecutionContext) (any, error)

func (v *StepValkey) IsTerminal() bool

func (v *StepValkey) StepName() string

func (v *StepValkey) StepWhen() Expr

func (v *StepValkey) ValidateStep(m *Manifest) error

type Telemetry ¶ added in v0.2.1

type Telemetry struct {
	ServiceName string   `hcl:"service_name,optional"`
	LogLevel    string   `hcl:"log_level,optional"`
	LogFormat   string   `hcl:"log_format,optional"`
	Redact      []string `hcl:"redact,optional"`
}

Telemetry configures structured logging output, log level thresholds, and key redaction.

type TypeSpec ¶ added in v0.2.1

type TypeSpec struct {
	Type      DataType
	SchemaRef string
	ElemType  *TypeSpec
}

TypeSpec encapsulates a scalar primitive, custom schema reference, or nested list.

Because TypeSpec contains a pointer field (ElemType), instances must never be compared using Go == or != operators. Use TypeSpec.Equal instead.

func ListType(elem TypeSpec) TypeSpec

func ObjectType(schemaRef string) TypeSpec

func ParseTypeSpec(raw string) (TypeSpec, error)

func ScalarType(dt DataType) (TypeSpec, error)

func TypeSpecFromCty(val cty.Value) (TypeSpec, error)

func (t TypeSpec) ElementSchemaRef() string

func (t TypeSpec) Equal(other TypeSpec) bool

func (t TypeSpec) IsArray() bool

func (t TypeSpec) IsObject() bool

func (t TypeSpec) IsScalar() bool

func (t TypeSpec) String() string