webindex

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 2026 License: MIT Imports: 46 Imported by: 0

Documentation

Overview

Package webindex analyzes GoForj route declarations and emits route and OpenAPI metadata.

Index

Constants

View Source 
const ArtifactPublicationLockFilename = ".webindex-artifacts.lock"

ArtifactPublicationLockFilename is the persistent cross-process lock name shared by webindex and GoForj artifact publishers.

View Source 
const ManifestVersion = "2"

ManifestVersion is the schema version for the API index output.

Variables

This section is empty.

Functions

func MatchActiveSourceFile added in v0.6.0 

func MatchActiveSourceFile(directory string, name string, buildTags ...string) (bool, error)

MatchActiveSourceFile reports whether the Go command would include one source file under the indexing process's active build environment. Explicit build tags take the same precedence over GOFLAGS as a command-line -tags flag.

Types

type ArtifactPublicationLock added in v0.6.0 

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

ArtifactPublicationLock holds process-local and operating-system directory locks for one canonical artifact set and must not be copied after first use.

func AcquireArtifactPublicationLock added in v0.6.0 

func AcquireArtifactPublicationLock(ctx context.Context, artifactPaths ...string) (*ArtifactPublicationLock, error)

AcquireArtifactPublicationLock lets coordinating publishers use the exact lock ordering and process-local registry used by webindex publication.

func (*ArtifactPublicationLock) Release added in v0.6.0 

func (lock *ArtifactPublicationLock) Release() error

Release relinquishes an artifact publication lock at most once and returns the same result to repeated callers.

type BodyShape 

type BodyShape struct {
	TypeName   string `json:"type_name,omitempty"`
	Schema     any    `json:"schema,omitempty"`
	Source     string `json:"source,omitempty"`
	Confidence string `json:"confidence,omitempty"`
}

BodyShape describes inferred request body information.

type Diagnostic 

type Diagnostic struct {
	Severity  string `json:"severity"`
	Code      string `json:"code"`
	Message   string `json:"message"`
	File      string `json:"file,omitempty"`
	Line      int    `json:"line,omitempty"`
	Operation string `json:"operation,omitempty"`
}

Diagnostic captures parser/indexer warnings and informational findings.

type DiagnosticsError added in v0.6.0 

type DiagnosticsError struct {
	Diagnostics []Diagnostic
}

DiagnosticsError reports findings that prevent publishing a trustworthy index.

func (*DiagnosticsError) Error added in v0.6.0 

func (e *DiagnosticsError) Error() string

Error summarizes the diagnostic failure without making callers parse individual messages.

type HandlerRef 

type HandlerRef struct {
	Expression string `json:"expression"`
	Package    string `json:"package,omitempty"`
	ImportPath string `json:"import_path,omitempty"`
	Receiver   string `json:"receiver,omitempty"`
	Function   string `json:"function,omitempty"`
	File       string `json:"file,omitempty"`
	Line       int    `json:"line,omitempty"`
}

HandlerRef points to the handler function/method.

type IndexOptions 

type IndexOptions struct {
	Root                 string
	OutPath              string
	DiagnosticsPath      string
	OpenAPIPath          string
	OpenAPI              OpenAPIOptions
	RouteCompositionPath string
	// BuildTags selects the same conditional source for syntax discovery and focused Go type loading.
	BuildTags []string
	Strict    bool
	SkipDir   func(path string, name string) bool
}

IndexOptions controls API index generation behavior.

type InputShape 

type InputShape struct {
	PathParams  []Parameter `json:"path_params,omitempty"`
	QueryParams []Parameter `json:"query_params,omitempty"`
	Headers     []Parameter `json:"headers,omitempty"`
	Cookies     []Parameter `json:"cookies,omitempty"`
	Body        *BodyShape  `json:"body,omitempty"`
}

InputShape describes request inputs inferred from AST.

type Manifest 

type Manifest struct {
	Version     string       `json:"version"`
	Operations  []Operation  `json:"operations"`
	Schemas     []Schema     `json:"schemas"`
	Diagnostics []Diagnostic `json:"diagnostics"`
}

Manifest is the canonical API index artifact.

func Run 

func Run(ctx context.Context, opts IndexOptions) (Manifest, error)

Run indexes API metadata from source and writes artifacts. @group Indexing Example: 

manifest, err := webindex.Run(context.Background(), webindex.IndexOptions{
	Root:    ".",
	OutPath: "webindex.json",
})

fmt.Println(err == nil, manifest.Version != "") 

// true true

func RunCached added in v0.6.2 

func RunCached(ctx context.Context, opts IndexOptions, cachePath string) (Manifest, error)

RunCached indexes API metadata while reusing a content-validated analysis cache at cachePath. Relative cache paths resolve from opts.Root. An empty path behaves like Run. When the active build cannot be fingerprinted safely, RunCached falls back to a full run without persisting state. @group Indexing

type OpenAPIDocument 

type OpenAPIDocument struct {
	OpenAPI    string                          `json:"openapi"`
	Info       map[string]string               `json:"info"`
	Paths      map[string]map[string]OpenAPIOp `json:"paths"`
	Components map[string]any                  `json:"components,omitempty"`
}

OpenAPIDocument is the OpenAPI 3.0 projection generated from the canonical API index.

func ProjectOpenAPI added in v0.6.0 

func ProjectOpenAPI(manifest Manifest, options OpenAPIOptions) (OpenAPIDocument, error)

ProjectOpenAPI projects a manifest with validated metadata, security, and contract overrides.

type OpenAPIInfoOptions added in v0.6.0 

type OpenAPIInfoOptions struct {
	Title       string
	Version     string
	Description string
}

OpenAPIInfoOptions controls the human-facing document metadata.

type OpenAPIMiddlewareSecurityRule added in v0.6.0 

type OpenAPIMiddlewareSecurityRule struct {
	Expression   string
	SourceFile   string
	Function     string
	Receiver     string
	Requirements []OpenAPISecurityRequirement
}

OpenAPIMiddlewareSecurityRule maps middleware attached by one source declaration to an explicit security policy. SourceFile must be a project-relative slash-separated Go file, Function is the enclosing declaration name, Receiver optionally restricts a method declaration, and Expression must exactly match Operation.Middleware.

type OpenAPIOp 

type OpenAPIOp struct {
	OperationID string                        `json:"operationId"`
	Summary     string                        `json:"summary,omitempty"`
	Description string                        `json:"description,omitempty"`
	Tags        []string                      `json:"tags,omitempty"`
	Parameters  []OpenAPIParameter            `json:"parameters,omitempty"`
	RequestBody map[string]any                `json:"requestBody,omitempty"`
	Responses   map[string]map[string]any     `json:"responses"`
	Security    *[]OpenAPISecurityRequirement `json:"security,omitempty"`
}

OpenAPIOp is the operation shape emitted for one indexed route.

type OpenAPIOperationOverride added in v0.6.0 

type OpenAPIOperationOverride struct {
	Match            OpenAPIOperationSelector
	Summary          string
	Description      string
	Tags             []string
	Parameters       []OpenAPIParameterOverride
	RequestBody      *OpenAPIRequestBodyOverride
	ReplaceResponses bool
	Responses        map[string]OpenAPIResponseOverride
	Security         *OpenAPISecurityPolicy
}

OpenAPIOperationOverride replaces evidence that source analysis cannot express unambiguously.

type OpenAPIOperationSelector added in v0.6.0 

type OpenAPIOperationSelector struct {
	ImportPath string
	Package    string
	Receiver   string
	Function   string
	Method     string
	Path       string
}

OpenAPIOperationSelector identifies exactly one operation without depending on its internal diagnostic ID.

type OpenAPIOptions added in v0.6.0 

type OpenAPIOptions struct {
	Info                    OpenAPIInfoOptions
	Operations              []OpenAPIOperationOverride
	SecuritySchemes         map[string]OpenAPISecurityScheme
	MiddlewareSecurity      map[string][]OpenAPISecurityRequirement
	MiddlewareSecurityRules []OpenAPIMiddlewareSecurityRule
}

OpenAPIOptions controls metadata and explicit contract overrides applied while projecting a manifest. Security is never inferred from middleware names: declare each scheme and map middleware explicitly. MiddlewareSecurityRules are preferred when identical expressions can occur in different source declarations; MiddlewareSecurity retains global expression-only compatibility. An operation override selector must match exactly once; use Method and Path when one handler serves several routes. Set ReplaceResponses when explicit responses supersede an unresolved or otherwise ambiguous set. Projection overrides refine OpenAPI only: they do not suppress Manifest diagnostics or make strict indexing accept unresolved source evidence such as a user-defined JSON marshaler.

type OpenAPIParameter 

type OpenAPIParameter struct {
	Name     string         `json:"name"`
	In       string         `json:"in"`
	Required bool           `json:"required,omitempty"`
	Schema   map[string]any `json:"schema,omitempty"`
	Example  any            `json:"example,omitempty"`
}

OpenAPIParameter is a projected path, query, header, or cookie parameter.

type OpenAPIParameterOverride added in v0.6.0 

type OpenAPIParameterOverride struct {
	In       string
	Name     string
	Required *bool
	Schema   any
	Example  any
}

OpenAPIParameterOverride refines one discovered path, query, header, or cookie parameter.

type OpenAPIProjectionError added in v0.6.0 

type OpenAPIProjectionError struct {
	Problems []string
}

OpenAPIProjectionError reports invalid or ambiguous explicit OpenAPI configuration.

func (*OpenAPIProjectionError) Error added in v0.6.0 

func (e *OpenAPIProjectionError) Error() string

Error formats every projection problem so configuration can be corrected in one pass.

type OpenAPIRequestBodyOverride added in v0.6.0 

type OpenAPIRequestBodyOverride struct {
	Remove    bool
	Required  *bool
	MediaType string
	Schema    any
	Example   any
}

OpenAPIRequestBodyOverride refines body requiredness or supplies an ambiguous media contract.

type OpenAPIResponseOverride added in v0.6.0 

type OpenAPIResponseOverride struct {
	Description string
	MediaType   string
	Schema      any
	Example     any
	Remove      bool
}

OpenAPIResponseOverride refines one status response or supplies an ambiguous media contract.

type OpenAPISecurityPolicy added in v0.6.0 

type OpenAPISecurityPolicy struct {
	Requirements []OpenAPISecurityRequirement `json:"requirements"`
}

OpenAPISecurityPolicy lists alternative requirements; schemes within one requirement are jointly required.

type OpenAPISecurityRequirement added in v0.6.0 

type OpenAPISecurityRequirement map[string][]string

OpenAPISecurityRequirement maps security scheme names to their required OAuth or OpenID scopes.

type OpenAPISecurityScheme added in v0.6.0 

type OpenAPISecurityScheme struct {
	Type             string `json:"type"`
	Description      string `json:"description,omitempty"`
	Name             string `json:"name,omitempty"`
	In               string `json:"in,omitempty"`
	Scheme           string `json:"scheme,omitempty"`
	BearerFormat     string `json:"bearerFormat,omitempty"`
	OpenIDConnectURL string `json:"openIdConnectUrl,omitempty"`
	Flows            any    `json:"flows,omitempty"`
}

OpenAPISecurityScheme describes an OpenAPI 3.0 security scheme without inferring policy from middleware names.

type Operation 

type Operation struct {
	ID         string             `json:"id"`
	Method     string             `json:"method"`
	Path       string             `json:"path"`
	Handler    HandlerRef         `json:"handler"`
	Metadata   *OperationMetadata `json:"metadata,omitempty"`
	Middleware []string           `json:"middleware,omitempty"`
	Inputs     InputShape         `json:"inputs"`
	Outputs    OutputShape        `json:"outputs"`
	// contains filtered or unexported fields
}

Operation describes one HTTP operation discovered in source.

type OperationMetadata added in v0.6.0 

type OperationMetadata struct {
	Summary     string                 `json:"summary,omitempty"`
	Description string                 `json:"description,omitempty"`
	Tags        []string               `json:"tags,omitempty"`
	Security    *OpenAPISecurityPolicy `json:"security,omitempty"`
}

OperationMetadata records human-authored contract context independently of route discovery evidence.

type OutputShape 

type OutputShape struct {
	Responses []ResponseShape `json:"responses,omitempty"`
}

OutputShape describes response outputs inferred from AST.

type Parameter 

type Parameter struct {
	Name       string `json:"name"`
	In         string `json:"in"`
	Required   bool   `json:"required"`
	Confidence string `json:"confidence"`
}

Parameter describes an input parameter.

type ResponseShape 

type ResponseShape struct {
	StatusCode  int    `json:"status_code"`
	TypeName    string `json:"type_name,omitempty"`
	Schema      any    `json:"schema,omitempty"`
	ContentType string `json:"content_type,omitempty"`
	Source      string `json:"source,omitempty"`
	Confidence  string `json:"confidence,omitempty"`
}

ResponseShape describes one possible response.

type Schema 

type Schema struct {
	Identity   string `json:"identity"`
	Name       string `json:"name"`
	Package    string `json:"package,omitempty"`
	TypeName   string `json:"type_name,omitempty"`
	Definition any    `json:"definition"`
	Confidence string `json:"confidence,omitempty"`
}

Schema records one canonical named Go contract and its deterministic projection.

Source Files

View all Source files

Directories

Path Synopsis
testfixture
routemutation/app
Package app defines the route-composition boundary used by runtime-mutation parity tests.
 Package app defines the route-composition boundary used by runtime-mutation parity tests.
routemutation/controllers
Package controllers provides route mutation fixtures whose runtime behavior must match indexed output.
 Package controllers provides route mutation fixtures whose runtime behavior must match indexed output.
routeparity/app
Package app composes the exact route groups used by the runtime parity fixture.
 Package app composes the exact route groups used by the runtime parity fixture.
routeparity/controllers
Package controllers provides route providers used to compare runtime registration with source indexing.
 Package controllers provides route providers used to compare runtime registration with source indexing.

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.