module

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package module holds the module contract and the module inspection, S6.

A module is one feature of an application. It states a name. It implements the optional interface of each concern that it contributes to: routes, inbox handlers, scheduled jobs, projections, migrations and the description that an agent reads.

Avero inspects each module one time at start. Avero does not use init for discovery. See the SDD, section 5.2 and S6.

Index

Constants

View Source
const ReportSchemaID = "https://avero.dev/schema/modules-report/v1"

ReportSchemaID names the schema that a JSON module report follows. See module/schema.json.

View Source
const SchemaSchemaID = "https://avero.dev/schema/model-report/v1"

SchemaSchemaID names the schema that a JSON model report follows. See module/schema_models.json.

Variables

View Source
var ModelSchema []byte

ModelSchema holds module/schema_models.json. `avero schema --json` emits a document that this schema accepts. See AN-3.

View Source
var ReportSchema []byte

ReportSchema holds module/schema.json. `avero modules --json` emits a document that this schema accepts. See AN-3.

Functions

This section is empty.

Types

type Contribution

type Contribution struct {
	// Module is the name of the module.
	Module string `json:"module"`
	// Interfaces names each optional interface that the module implements,
	// in alphabetical order. It is empty for a module that implements none.
	Interfaces []string `json:"interfaces"`
	// Routes lists the routes of the module.
	Routes []RouteDesc `json:"routes"`
	// InboxHandlers names each message handler of the module.
	InboxHandlers []string `json:"inboxHandlers"`
	// Projections names each projection of the module.
	Projections []string `json:"projections"`
	// Jobs names each scheduled job of the module.
	Jobs []string `json:"jobs"`
	// Migrations reports a module that carries migration files.
	Migrations bool `json:"migrations"`
	// Description is the description of the module. The module system builds
	// it from the inspection when the module implements no DescribeModule.
	Description *Description `json:"description"`
}

Contribution is one row of the contribution table. It states what one module contributes.

type DescribeModule

type DescribeModule interface {
	Describe() Description
}

DescribeModule states the description that an agent reads. A module that does not implement it still gets a description, which the module system builds from the inspection. See AN-3.

type Description

type Description struct {
	// Name is the name of the module.
	Name string `json:"name"`
	// Routes lists the routes of the module.
	Routes []RouteDesc `json:"routes"`
	// Models lists the persistent models of the module.
	Models []ModelDesc `json:"models"`
	// Events lists the events that the module publishes.
	Events []EventDesc `json:"events"`
	// Projections names each projection of the module.
	Projections []string `json:"projections"`
	// InboxTypes names each message type that the module reads.
	InboxTypes []string `json:"inboxTypes"`
}

Description states what one module contributes. `avero modules --json` emits it, and the MCP server of S16 returns it. See AN-3.

type EventDesc

type EventDesc struct {
	// Name is the name of the event type.
	Name string `json:"name"`
	// Fields lists the fields of the event.
	Fields []FieldDesc `json:"fields"`
}

EventDesc is one event of a module.

type Fault

type Fault struct {
	// File is the file that holds the fault. It is empty when no position
	// applies.
	File string `json:"file"`
	// Line is the line that holds the fault.
	Line int `json:"line"`
	// Message states the fault.
	Message string `json:"message"`
	// Repair states what to do. It is one sentence.
	Repair string `json:"repair"`
}

Fault is one module fault. It names the position in the code that the person wrote, states what went wrong, and states the repair in one sentence. See DX-6 and DX-7.

func (*Fault) Error

func (f *Fault) Error() string

Error returns the position, the message and the repair.

type Faults

type Faults struct {
	Faults []*Fault `json:"faults"`
}

Faults holds every fault that one inspection found. The module system reports every fault, not only the first.

func (*Faults) Error

func (l *Faults) Error() string

Error returns a count and one entry for each fault.

func (*Faults) Unwrap

func (l *Faults) Unwrap() []error

Unwrap returns each fault so that errors.As reaches a single one.

type FieldDesc

type FieldDesc struct {
	// Name is the name of the field.
	Name string `json:"name"`
	// Type is the Go type of the field.
	Type string `json:"type"`
}

FieldDesc is one field of a model or of an event.

type HTTPModule

type HTTPModule interface {
	Routes(r *router.Router)
}

HTTPModule contributes routes. The module registers them on the router that the module system passes to it.

type InboxHandler

type InboxHandler interface {
	// HandlerName returns the name of the handler. The name and the message
	// identifier form the dedupe key.
	HandlerName() string
	// MessageType returns the type of the message that the handler reads.
	MessageType() string
}

InboxHandler is one message handler. The module system reads the name of the handler and the type of the message. S8 defines the concrete handler, and it satisfies this interface.

type InboxModule

type InboxModule interface {
	InboxHandlers() []InboxHandler
}

InboxModule contributes message handlers. S8 runs them.

type Job

type Job struct {
	// Name identifies the job. It appears in the contribution table.
	Name string
	// Every states the period, such as 1m. A runner reads it.
	Every string
	// Run performs the work.
	Run func(ctx context.Context) error
}

Job is one scheduled unit of work.

type MigrationModule

type MigrationModule interface {
	Migrations() fs.FS
}

MigrationModule contributes migration files. The file system holds the SQL files of one module.

type ModelDesc

type ModelDesc struct {
	// Name is the name of the Go type.
	Name string `json:"name"`
	// Table is the name of the database table.
	Table string `json:"table"`
	// Fields lists the fields of the model.
	Fields []FieldDesc `json:"fields"`
}

ModelDesc is one persistent model of a module.

type ModelRow

type ModelRow struct {
	// Module is the module that owns the model.
	Module string `json:"module"`
	// Name is the name of the Go type.
	Name string `json:"name"`
	// Table is the name of the database table.
	Table string `json:"table"`
	// Fields lists the fields of the model.
	Fields []FieldDesc `json:"fields"`
}

ModelRow is one model of one module.

type Module

type Module interface {
	Name() string
}

Module is one feature of an application. Every module states a name. The name appears in the contribution table and in a fault message, so it must stay stable.

type Projection

type Projection interface {
	// ProjectionName returns the name of the projection. The checkpoint row
	// carries it.
	ProjectionName() string
}

Projection is one read model projection. The module system reads the name. S9 defines the concrete projection, and it satisfies this interface.

type ProjectorModule

type ProjectorModule interface {
	Projections() []Projection
}

ProjectorModule contributes projections. S9 runs them.

type Report

type Report struct {
	// Modules holds one row for each module, in registration order, so that
	// two runs give the same order. See AN-4.
	Modules []Contribution `json:"modules"`
}

Report lists the contribution of every module. `avero modules` prints it.

func (*Report) MarshalJSON

func (rep *Report) MarshalJSON() ([]byte, error)

MarshalJSON emits the report with a stable schema. Every member holds an array, so a reader needs no null test. See AN-3 and AN-4.

func (*Report) Module

func (rep *Report) Module(name string) (Contribution, bool)

Module returns the row of this module.

func (*Report) String

func (rep *Report) String() string

String returns the contribution table with a header row and one row for each module.

type RouteDesc

type RouteDesc struct {
	// Method is the HTTP method, or * for a mounted handler.
	Method string `json:"method"`
	// Pattern is the pattern that the module registered.
	Pattern string `json:"pattern"`
	// Handler is the name of the function that serves the route.
	Handler string `json:"handler"`
}

RouteDesc is one route of a module.

type ScheduleModule

type ScheduleModule interface {
	Schedule(s *Scheduler)
}

ScheduleModule contributes scheduled jobs.

type Scheduler

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

Scheduler collects the jobs of the modules. A ScheduleModule adds its jobs to it. The runner of the jobs arrives with a later subsystem.

func (*Scheduler) Add

func (s *Scheduler) Add(j Job)

Add records one job.

func (*Scheduler) Jobs

func (s *Scheduler) Jobs() []Job

Jobs returns the recorded jobs in registration order.

type SchemaReport

type SchemaReport struct {
	// Models holds one row for each model, ordered by module and then by
	// model name, so that two runs give the same order. See AN-4.
	Models []ModelRow `json:"models"`
}

SchemaReport lists the models of every module. `avero schema` prints it.

func Schema

func Schema(s *Set) *SchemaReport

Schema returns the models that the modules describe.

func (*SchemaReport) MarshalJSON

func (rep *SchemaReport) MarshalJSON() ([]byte, error)

MarshalJSON emits the report with a stable schema. See AN-3.

func (*SchemaReport) String

func (rep *SchemaReport) String() string

String returns a table with one row for each model.

type Set

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

Set holds the modules of one application and the result of the inspection.

Modules performs the inspection one time. A method of Set reads the result. A method never calls a module again.

func Modules

func Modules(ms ...Module) *Set

Modules inspects each module one time and returns the result.

It calls each optional method one time, in the order of the arguments. It records a fault for a module with no name, for a name that two modules share, for a route registration that is wrong, and for one pattern that two modules register. Err returns the faults.

set := avero.Modules(billing.New(db), catalog.New(db))
if err := set.Attach(r); err != nil {
    os.Exit(avero.Exit(os.Stderr, err))
}

func (*Set) Attach

func (s *Set) Attach(r *router.Router) error

Attach adds the routes of every HTTPModule to r. It returns the faults and adds no route when the inspection found one.

The prefix and the middleware of r apply to every route, so a group scopes a whole module.

func (*Set) Err

func (s *Set) Err() error

Err returns every fault that the inspection found, or nil. The caller stops the process on a fault. See DX-8.

func (*Set) InboxHandlers

func (s *Set) InboxHandlers() []InboxHandler

InboxHandlers returns the handlers of every InboxModule.

func (*Set) Jobs

func (s *Set) Jobs() []Job

Jobs returns the scheduled jobs of every ScheduleModule.

func (*Set) Migrations

func (s *Set) Migrations() []fs.FS

Migrations returns the file system of every MigrationModule, in registration order.

func (*Set) Projections

func (s *Set) Projections() []Projection

Projections returns the projections of every ProjectorModule.

func (*Set) Report

func (s *Set) Report() (*Report, error)

Report returns the contribution table. It returns every fault and no report, so a fault stops the process before it serves.

func (*Set) WriteReport

func (s *Set) WriteReport(w io.Writer, asJSON bool) error

WriteReport writes the report to w. It writes the JSON document when asJSON is true, and the table when it is false. It returns the faults and writes nothing when the inspection found one. `avero modules` calls it. See S14.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL