The component catalog

The catalog lists the components of the group that an operator meets, and serves the logo of each. The two answer from one index that is part of the package, so they say the same thing about a component. The normative rules are in 003-application-catalog.

What the listing holds

The listing is wider than the deployment form. An entry tells whether the form configures it (an application that an operator gives settings, or a supporting component that no operator configures), and whether the operator turns it on and off (an application such as mastodon, or a component that each deployment runs, such as authelia). A component that each deployment runs and that has a web UI of its own also gives the label it answers on, so that a surface can send an operator to it below the domain of the deployment. An application that the operator turns on uses the label that the operator chose in its configuration instead.

That is the reason for the listing. A front-end can take the name of an application from the schema that it renders the form from, but a supporting component is in no schema. Without the listing, a surface that shows what a deployment runs would need a list of its own.

Each entry also carries the title that the project gives itself, its description, its home page, and the place where its logo is served, or none when the project publishes no artwork; the surface then shows the name alone.

Artwork

The logo is the SVG that the project itself ships, served under the same name as in the listing. A front-end shows it beside the name of an application or instance.

The bytes are baked at build time, not fetched. The catalog of core takes the artwork of each component from the source of its own package, and publishes it with the index of the listing. Thus serving a logo is a file read: no eval, no network, and nothing to authenticate, on the same basis as the public schema.

The response has a validator taken from the bytes of the artwork, and a cache lifetime of one hour. The validator comes from the content because all files in the Nix store share one modification time, which a validator is usually made of; two logos of the same size would then look the same. A client that holds a logo validates it again and gets "not modified".

A miss is one "not found" for its three causes: a component that the catalog does not name, one that has no artwork, and one whose artwork is absent. A browser cannot act on the difference. A supporting component can have no artwork, because a project may publish none; the build fails when an application of the operator form has none. A component without artwork has no logo in the listing, so a front-end that follows the listing does not ask for a logo that is not there.