model

Documentation

Overview

Package model defines the transport-neutral intermediate representation (IR).

Hard rules (see docs/SPEC.md §4.2):

• No HTTP verbs, paths, status codes, or any transport concept in core fields. Transport metadata lives only in Ext, keyed by emitter name.
• The whole IR round-trips through encoding/json losslessly: exported fields only, strings not go/types objects, and Ext leaves are JSON-round-trippable.

Index

• type Directive
• type Field
• type Method
• type Service
• type StreamKind
• type TypeRef

Types

type Directive

type Directive struct {
	Name string // e.g. "route", "service"
	Args string // raw remainder, e.g. "GET /orders/{id}"
	Pos  string // "orders.go:12"
}

Directive is a raw, uninterpreted framework:* annotation. Semantics belong to whoever consumes it (the parser for "service"; emitters for their own).

type Field

type Field struct {
	Name     string
	GoType   string            // rendered Go type expression, e.g. "[]Item", "time.Time"
	Imports  []string          // sorted import paths referenced by GoType, e.g. ["time"]; empty for builtins/same-package
	Tags     map[string]string // parsed struct tags: path, query, json, header (name portion)
	Optional bool              // pointer, or has json ",omitempty"

	// TextUnmarshaler is true when the field's type or its pointer implements
	// encoding.TextUnmarshaler — i.e. an addressable value of the field type
	// can be unmarshaled via the method. Emitters bind such fields as
	// path/query params.
	TextUnmarshaler bool
	// TextMarshaler is true when the field's type or its pointer implements
	// encoding.TextMarshaler — i.e. an addressable value of the field type
	// can be marshaled via the method. Emitters bind such fields as
	// path/query params.
	TextMarshaler bool
}

Field is one exported struct field, fully rendered to strings at parse time.

type Method

type Method struct {
	Name       string
	Input      TypeRef
	Output     TypeRef
	Stream     StreamKind
	Doc        string // doc comment minus framework:* directives
	Pos        string // "orders.go:12" — rendered, no go/token objects
	Directives []Directive
	Ext        map[string]any
}

Method is one interface method.

type Service

type Service struct {
	Name string // Go interface name, e.g. "Orders"
	// Package is the import path of the defining package.
	Package string
	// PackageName is the Go package identifier (from pkg.Name), e.g. "api". It is
	// not derivable from Package: for /v2-style module paths the import path's
	// last segment ("v2") differs from the actual package clause.
	PackageName string
	BasePath    string // optional, from framework:service base=
	Methods     []Method
	Directives  []Directive // framework:* directives on the interface, stripped from doc
	Ext         map[string]any
}

Service is one Go interface's worth of API surface.

type StreamKind

type StreamKind int

StreamKind classifies a method's streaming shape. Only Unary is implemented in the PoC; the rest are reserved so the parser can reject them explicitly.

const (
	Unary StreamKind = iota
	ServerStream
	ClientStream
	BidiStream
)

type TypeRef

type TypeRef struct {
	Name       string
	ImportPath string
	Fields     []Field // exported fields only
}

TypeRef is a resolved struct type (request or response).