model

type AuxService struct {
	// Human readable service name.
	Name string `json:"name"`
	// Container runtime behaviour (stop handling, command, tty).
	RunConfig RunConfig `json:"run_config"`
	// Files and directories of the module repository to be mounted into the
	// container, keyed by mount point.
	BindMounts map[string]BindMount `json:"bind_mounts"` // {mntPoint:BindMount}
	// In-memory file systems to be created for the container, keyed by mount
	// point.
	Tmpfs map[string]TmpfsMount `json:"tmpfs"` // {mntPoint:TmpfsMount}
	// Volumes to be mounted, mapping mount point to a volume name declared in
	// Module.Volumes.
	Volumes map[string]string `json:"volumes"` // {mntPoint:volName}
	// Configuration values to be passed as environment variables, mapping
	// variable name to a config reference of Module.Configs.
	Configs map[string]string `json:"configs"` // {refVar:ref}
	// Addresses of module services, keyed by the environment variable that
	// receives the address.
	SrvReferences map[string]SrvRefTarget `json:"srv_references"` // {refVar:SrvRefTarget}
	// Addresses of services provided by modules listed in
	// Module.Dependencies, keyed by the environment variable that receives
	// the address.
	ExtDependencies map[string]ExtDependencyTarget `json:"ext_dependencies"` // {refVar:ExtDependencyTarget}
}

type BindMount struct {
	// Path of the file or directory relative to the module directory.
	Source string `json:"source"`
	// Mount the source read-only.
	ReadOnly bool `json:"read_only"`
}

type CPUArch = string

type ConfigTypeOption struct {
	// Option value, typed according to DataType.
	Value any `json:"value"`
	// Data type of Value. Depending on the option it must either match the
	// DataType of the ConfigValue (e.g. min and max of number) or a type
	// fixed by the option itself (e.g. min_len of text is always an int).
	DataType DataType `json:"data_type"`
}

type ConfigTypeOptions map[string]ConfigTypeOption

type ConfigValue struct {
	// Default value used when the user provides none, or nil if there is no
	// default.
	Default any `json:"default"`
	// Allowed values as a slice matching DataType, or nil if the value is not
	// restricted.
	Options any `json:"options"`
	// Accept values outside of Options. Only meaningful if Options is set.
	OptExt bool `json:"opt_ext"`
	// Config type selecting the validation definition applied to user input
	// (e.g. text, number). Empty if the value cannot be set by the user.
	Type string `json:"type"`
	// Type specific options constraining user input, keyed by option name as
	// supported by Type (e.g. min, max and step for number, regex, min_len
	// and max_len for text).
	TypeOpt ConfigTypeOptions `json:"type_opt"`
	// Data type of the value (see BoolType, Int64Type, Float64Type and
	// StringType). Defaults to StringType when the modfile omits it.
	DataType DataType `json:"data_type"`
	// The config holds multiple values of DataType rather than a single one.
	IsSlice bool `json:"is_slice"`
	// Delimiter used to join multiple values into the single string passed to
	// a container. Defaults to "," when the modfile omits it. Only meaningful
	// if IsSlice is set.
	Delimiter string `json:"delimiter"`
	// The module cannot be deployed unless a value is available. A required
	// config must either have a Default or a user input defined for it.
	Required bool `json:"required"`
}

type Configs map[string]ConfigValue

type DataType = string

type ExtDependencyTarget struct {
	// ID of the required module, must be a key of Module.Dependencies.
	ID string `json:"id"`
	// Service reference within the required module.
	Service string `json:"service"`
	// Optional template wrapping the resolved address, containing the {ref}
	// placeholder (e.g. http://{ref}/api).
	Template string `json:"template"`
}

type File struct {
	// Optional path relative to the module directory of a file providing the
	// default content.
	Source string `json:"source"`
	// Content type of the file (e.g. generic, json, yaml), used to present a
	// suitable editor and to validate user input.
	Type string `json:"type"`
	// The module cannot be deployed unless content is available, either from
	// Source or from user input.
	Required bool `json:"required"`
}

type HostResTarget struct {
	// Reference of the host resource, must be a key of
	// Module.HostResources.
	Ref string `json:"ref"`
	// Attach the resource read-only.
	ReadOnly bool `json:"read_only"`
}

type HostResource struct {
	Resource
}

type HttpEndpoint struct {
	// Human readable endpoint name.
	Name string `json:"name"`
	// Port the service listens on. Defaults to 80 when the modfile omits it.
	Port int `json:"port"`
	// Internal path requests are forwarded to. Empty forwards to the root
	// path.
	Path string `json:"path"` // internal path
	// Reverse proxy behaviour for this endpoint.
	ProxyConf HttpEndpointProxyConf `json:"proxy_conf"`
	// String substitutions applied to responses of this endpoint.
	StringSub HttpEndpointStrSub `json:"string_sub"`
}

type HttpEndpointProxyConf struct {
	// Headers to append to or overwrite on requests sent downstream.
	Headers map[string]string `json:"headers"`
	// Allow connections to be upgraded to websocket.
	WebSocket bool `json:"websocket"`
	// Timeout for reading a response from downstream. Zero leaves the choice
	// to the gateway.
	ReadTimeout time.Duration `json:"read_timeout"`
}

type HttpEndpointStrSub struct {
	// Replace only the first occurrence of each filter instead of all
	// occurrences.
	ReplaceOnce bool `json:"replace_once"`
	// Restrict substitution to responses with these MIME types. Empty applies
	// to all responses. Entries must be unique.
	MimeTypes []string `json:"mime_types"`
	// Substitutions to apply, mapping the string to search for to its
	// replacement. The replacement may contain the {loc} placeholder, which
	// expands to the endpoint's external location
	// (e.g. `href="/` -> `href="{loc}/`).
	Filters map[string]string `json:"filters"`
}

type Input struct {
	// Input name, used as the label of the input field.
	Name string `json:"name"`
	// Short text describing what the user is expected to provide.
	Description string `json:"description"`
	// Optional reference of the group this input belongs to, must be a key of
	// Inputs.Groups.
	Group string `json:"group"`
}

type InputGroup struct {
	// Group name, used as the heading of the group.
	Name string `json:"name"`
	// Short text describing the group.
	Description string `json:"description"`
	// Optional reference of the parent group, must be a key of
	// Inputs.Groups. Cyclic references are rejected during validation.
	Group string `json:"group"`
}

type Inputs struct {
	// Inputs for selecting host resources, keyed by a reference of
	// Module.HostResources.
	Resources map[string]Input `json:"resources"` // {ref:Input}
	// Inputs for selecting secrets, keyed by a reference of Module.Secrets.
	Secrets map[string]Input `json:"secrets"` // {ref:Input}
	// Inputs for setting configuration values, keyed by a reference of
	// Module.Configs.
	Configs map[string]Input `json:"configs"` // {ref:Input}
	// Inputs for providing file content, keyed by a reference of
	// Module.Files. Every file requires an input.
	Files map[string]Input `json:"files"` // {ref:Input}
	// Inputs for providing the files of a file group, keyed by a reference of
	// Module.FileGroups. Every file group requires an input.
	FileGroups map[string]Input `json:"file_groups"` // {ref:Input}
	// Groups for categorising the inputs above, keyed by group reference.
	Groups map[string]InputGroup `json:"groups"` // {ref:InputGroup}
}

type Module struct {
	// Unique module identifier, a url without schema
	// (e.g. github.com/user/repo). Used as key when other modules declare a
	// dependency on this module.
	ID string `json:"id"`
	// Human readable module name.
	Name string `json:"name"`
	// Short text describing the module.
	Description string `json:"description"`
	// Free-form tags used for categorising and filtering modules.
	Tags Set[string] `json:"tags"`
	// Module license name (e.g. Apache License 2.0).
	License string `json:"license"`
	// Module author.
	Author string `json:"author"`
	// Module version, prefixed with 'v' and adhering to semantic versioning
	// (see https://semver.org/).
	Version string `json:"version"`
	// CPU architectures the module supports. Entries must be known
	// architectures (see CPUArchMap); an empty set means unrestricted.
	Architectures Set[CPUArch] `json:"architectures"`
	// Services the module consists of, keyed by service reference
	// ({ref:Service}). Each service becomes one container per deployment and
	// its reference is used to address it from other services, from aux
	// services and from dependent modules.
	Services map[string]Service `json:"services"` // {ref:Service}
	// Names of the volumes the module requires. Volumes are
	// created per deployment; services attach them via Service.Volumes.
	Volumes Set[string] `json:"volumes"` // {volName}
	// Other modules that must be installed and deployed for this module to
	// work, mapping module ID to a semantic version range
	// (e.g. ">=v1.0.2;<v2.0.0"). Services address services of these modules
	// via Service.ExtDependencies.
	Dependencies map[string]string `json:"dependencies"` // {moduleID:moduleVersion}
	// Host resources (devices, sockets, ...) required by services, keyed by
	// resource reference. The concrete resource is selected at deployment
	// time from the resources the host manager offers.
	HostResources map[string]HostResource `json:"host_resources"` // {ref:HostResource}
	// Secrets (certificates, keys, ...) required by services, keyed by secret
	// reference. The concrete secret is selected at deployment
	// time from the secrets the secret manager holds.
	Secrets map[string]Secret `json:"secrets"` // {ref:Secret}
	// Files whose content is supplied or edited by the user, keyed by file
	// reference. Services mount them via Service.Files.
	Files map[string]File `json:"files"` // {ref:File}
	// References of file groups. A file group collects an arbitrary
	// number of user provided files under a common base path; services attach
	// a group via Service.FileGroups.
	FileGroups Set[string] `json:"file_groups"` // {ref}
	// Configuration values required by services, keyed by config reference.
	// Services receive them as environment variables via Service.Configs.
	Configs Configs `json:"configs"` // {ref:ConfigValue}
	// Auxiliary services that module services may deploy at runtime, keyed by
	// aux service reference. Unlike Services these are not started with
	// the deployment but on demand.
	AuxServices map[string]AuxService `json:"aux_services"` // {ref:AuxService}
	// Image sources allowed for aux services (e.g.
	// ghcr.io/senergy-platform/*). A trailing '*' acts as a wildcard;
	// deploying an aux service whose image matches no entry is rejected.
	AuxImgSrc Set[string] `json:"aux_img_src"`
	// Metadata describing the inputs the user has to provide when deploying
	// the module (resource and secret selection, config values, files).
	Inputs Inputs `json:"inputs"`
}

type Port struct {
	// Human readable port name.
	Name string `json:"name"`
	// Port number inside the container. The combination of number and
	// protocol must be unique within a service.
	Number int `json:"number"`
	// Transport protocol, defaults to "tcp" when the modfile omits it.
	Protocol PortProtocol `json:"protocol"`
	// Host ports the container port is published on. Empty means no explicit
	// binding is requested. Bindings must not collide with those of other
	// services of the module.
	Bindings []int `json:"bindings"`
}

type PortProtocol = string

type Resource struct {
	// Tags aiding identification of a matching resource. A tag combination
	// that yields exactly one candidate allows selecting the resource without
	// user interaction.
	Tags Set[string] `json:"tags"`
	// The module cannot be deployed unless a resource is selected. A required
	// resource must either carry tags or have a user input defined for it.
	Required bool `json:"required"`
}

type RunConfig struct {
	// Grace period the container engine waits for the container to exit
	// before killing it. Defaults to 5s when the modfile omits it.
	StopTimeout time.Duration `json:"stop_timeout"`
	// Signal used to stop the container (e.g. SIGTERM). Empty leaves the
	// choice to the container engine.
	StopSignal string `json:"stop_signal"`
	// Allocate a pseudo TTY for the container.
	PseudoTTY bool `json:"pseudo_tty"`
	// Command to run instead of the image's default command, given as
	// argument list. Empty keeps the image default.
	Command []string `json:"command"`
}

type Secret struct {
	Resource
	// Secret type as defined by the secret manager (e.g. certificate,
	// basic-auth, api-key, client-id, private-key). It determines which items
	// a SecretTarget may address.
	Type string `json:"type"`
}

type SecretTarget struct {
	// Reference of the secret, must be a key of Module.Secrets.
	Ref string `json:"ref"`
	// Optional item of the secret to use, as defined by the secret type.
	// Empty selects the secret's default item.
	Item string `json:"item"`
}

type Service struct {
	// Human readable service name.
	Name string `json:"name"`
	// Container image, versioned via tag or digest (e.g. srv-image:v1.0.0).
	Image string `json:"image"`
	// Container runtime behaviour (stop handling, command, tty).
	RunConfig RunConfig `json:"run_config"`
	// Files and directories of the module repository to be mounted into the
	// container, keyed by mount point.
	BindMounts map[string]BindMount `json:"bind_mounts"` // {mntPoint:BindMount}
	// In-memory file systems to be created for the container, keyed by mount
	// point.
	Tmpfs map[string]TmpfsMount `json:"tmpfs"` // {mntPoint:TmpfsMount}
	// Volumes to be mounted, mapping mount point to a volume name declared in
	// Module.Volumes.
	Volumes map[string]string `json:"volumes"` // {mntPoint:volName}
	// Host resources to be passed into the container, keyed by mount point.
	// Depending on the type reported by the host manager the resource
	// is attached as a device or as a bind mount.
	HostResources map[string]HostResTarget `json:"host_resources"` // {mntPoint:HostResTarget}
	// Secrets to be mounted into the container as read-only files, keyed by
	// mount point.
	SecretMounts map[string]SecretTarget `json:"secret_mounts"` // {mntPoint:SecretTarget}
	// Secrets to be passed to the container as environment variables, keyed
	// by variable name.
	SecretVars map[string]SecretTarget `json:"secret_vars"` // {refVar:SecretTarget}
	// User provided files to be mounted, mapping mount point to a
	// file reference of Module.Files.
	Files map[string]string `json:"files"` // {mntPoint:ref}
	// File groups to be mounted, mapping the base path within the
	// container to a group reference of Module.FileGroups ({basePath:ref}).
	// Every file of the group is mounted at basePath joined with the relative
	// path the user assigned to it.
	FileGroups map[string]string `json:"file_groups"` // {basePath:ref}
	// Configuration values to be passed as environment variables, mapping
	// variable name to a config reference of Module.Configs.
	Configs map[string]string `json:"configs"` // {refVar:ref}
	// Addresses of other services of the same module, keyed by the
	// environment variable that receives the address.
	SrvReferences map[string]SrvRefTarget `json:"srv_references"` // {refVar:SrvRefTarget}
	// Endpoints of the service to be published via the api gateway, keyed by
	// the external path they are served under.
	// External paths must be unique within a module.
	HttpEndpoints map[string]HttpEndpoint `json:"http_endpoints"` // {externalPath:HttpEndpoint}
	// Addresses of services provided by modules listed in
	// Module.Dependencies, keyed by the environment variable that receives
	// the address.
	ExtDependencies map[string]ExtDependencyTarget `json:"ext_dependencies"` // {refVar:ExtDependencyTarget}
	// Container ports to be exposed and optionally published on the host.
	Ports []Port `json:"ports"`
	// Device cgroup rules to be set for the container, passed through to the
	// container engine (e.g. "c 13:* rwm").
	DeviceCGroupRules []string `json:"device_cgroup_rules"`
}

type Set[T comparable] map[T]struct{}

type SrvRefTarget struct {
	// Reference of the target service, must be a key of Module.Services.
	Ref string `json:"ref"`
	// Optional template wrapping the resolved address, containing the {ref}
	// placeholder (e.g. http://{ref}/api).
	Template string `json:"template"`
}

type TmpfsMount struct {
	// Size of the file system in bytes.
	Size int64 `json:"size"`
	// Linux file mode of the mounted file system. Defaults to 0770 when the
	// modfile omits it.
	Mode fs.FileMode `json:"mode"`
}