Fediversity API

Usage

A hosting provider bills its operators for the use of their deployments. GET /usage (usage_list) gives the usage periods of the deployments that the caller can see, as for GET /deployments. A period is the time in which a deployment ran one configuration:

  • Each build that succeeded and is not a destroy starts a period when it finishes. The next build of the deployment that succeeds, a destroy included, ends it. The last period of a deployment that is not destroyed has no end.
  • A failed or canceled build changes no period, because the deployment then keeps what the last build that succeeded deployed.
  • A period has the configuration and the module source of its build, and whether the build suspended the deployment. A suspended deployment stops its instances and keeps its volumes. A build records the flag of the deployment row when the submit creates it. A build that api recorded before it kept the flag has null.
  • A period has the domain that its configuration serves the applications below, and the domain that the deployment holds at the registrar account of the provider in that period, or null. A deploy registers the domain, or uses the registration that the deployment has, when the curation states a domainRegistration for the deployment method, and the domain is neither the apex of the provider nor below it, as registration in core/effects/tf/incus/operator/effect.nix. Each build records this value from the curation at its submit, thus a later change of the curation does not change the period. For a build that api recorded before it kept the value, api calculates it from the curation that it has now. The registrar keeps a domain after the destroy of its deployment, thus the domain_events below tell how long the account holds it.
  • since and until limit the result to the periods that overlap that time. api does not cut a period to these times, thus the caller decides how to bill a period that starts or ends outside them.

The domain_events of the result tell what the registrar account of the provider charged for the domains of these deployments, oldest first. Each event has its domain, its deployment_id, its cost in minor units of its currency (or null when api does not know it), and the expiration_date of the registration after the event:

  • register and transfer: a deploy registered the domain, or transferred it into the account, at the cost that the registrar gave for the order. The deploy writes this operation in domain.json of its build (output "domain" of core/effects/tf/incus/operator/registrar.tf), also when it fails after the order.
  • adopt: a deploy took a domain that the account held already, thus it has no cost. A next deploy of the deployment that holds the domain records no event.
  • A deploy that fails writes domain.json from its state, and a destroy writes it from its state before it starts. That state can have an order that the deployment recorded already, as after a release. Thus api records the operation of a failed build or of a destroy only when no event of the deployment for the domain has the same expiration_date or a later one. When the operation has no expiration_date, as for a pending transfer, api records it only when the deployment has no event of the domain. A deploy that stops before tofu writes the order to its state, as at a crash or a cancel, records no event: the next build of the deployment records the order.
  • renew: the expiry of the domain in the snapshot of registrar-domains moved forward by one year or more. The cost is the renewal price of one year in that snapshot, times the years that the expiry moved. A change of the expiry of less than half a year is not a renewal. The event is for the deployment that claims the domain, else for the deployment of the last start event.
  • release: the domain left the account: it is not in the snapshot, or it has the status DEL. A next deploy of the domain records a start event again. A destroy does not remove the domain from the account and does not change its renewal (on_destroy = "retain" in core/effects/tf/incus/operator/registrar.tf). The registrar removes the domain at its expiry only when its renewal is off. Thus the release after a destroy comes when the domain leaves the account: at about the expiration_date of the last event when its renewal is off, or after a transfer of the domain.

The api records renew and release only when registrarSnapshot of the NixOS module of api points to the snapshot (fediversity-api-domain-renewals runs at each change of it). since and until limit the events to the ones that api recorded at or after since and before until. The events have no link to a deployment row, thus they stay after a destroy.

api keeps each build after the destroy of its deployment, thus a deployment that the front-end deleted still has its periods. The front-end must keep the deleted deployments in the deployment_ids of its answer to bill them. The panel keeps the row of a deleted deployment, and gives its id to usage_list only, until the removal of the operator account.

The periods follow the builds, not the instances. They do not show the use of an application, for example the number of its users or of its mailboxes. api does not give the storage or the compute of a deployment: the telemetry of the provider gives the size of its PostgreSQL databases and garage buckets, and the CPU, memory, network and disk use of its incus instances, in Mimir with the label deployment_id. core/components/hosting-provider/node-metrics.nix and the incus scrape of core/setups/hosts-common.nix state how.