Function Custom Domains

Function custom domains map one exact hostname to one function. A request to https://feeds.example.com/shows/abc.xml?download=1 reaches the bound function with /shows/abc.xml?download=1 unchanged.

MVP behavior

• One exact hostname maps to one (project, function) pair.
• The complete path and query string are preserved. Amba does not strip a function-name prefix or rewrite paths on a custom hostname.
• Wildcard hostnames, path-based mappings, and path rewrites are not part of this first release. An exact apex hostname is accepted but gets no special DNS handling. Standard activation still requires a real CNAME record at authoritative DNS. Provider-native CNAME-at-root flattening works only when the provider stores that record as a CNAME; ALIAS, ANAME, and copied A/AAAA addresses do not preserve the required relationship. Use www or another subdomain when your provider cannot store an apex CNAME.
• Attaching feeds.example.com does not create www.feeds.example.com. Attaching an apex likewise creates no www alias. Automatic www handling for a separately purchased registrable domain does not apply here.
• The function's existing public/private and rate-limit policy remains authoritative.

Attach and validate

Deploy the function first, then attach the hostname:

amba functions deploy ./functions/feed.ts --name feed --public
amba functions domains attach feed feeds.example.com

The attach response prints a CNAME target and any ownership/certificate validation records. Publish every returned DNS record with the DNS provider that controls the hostname. When the hostname is inside an active domain bought through Amba, the attach response may instead report dns_autoconfigured: true and the number of records published automatically. Ownership and certificate issuance are independent: the hostname is live only when ownership_status and cert_status are both active and required routing reconciliation has succeeded (live: true).

For every hostname, follow the returned dns_record_type and dns_note literally. The safety note is unconditional; apex classification does not decide whether it is shown. An ALIAS or ANAME may resolve to the same edge addresses and TLS may even appear healthy, while hostname activation remains pending and requests fail at the edge. Do not call the hostname live from cert_status or a TLS handshake alone.

Attaching an externally managed domain to an Amba Site does not transfer its DNS zone to Amba. If the domain was not bought through Amba and its authoritative nameservers remain elsewhere, publish the returned function-domain records with that DNS provider even when the apex or www already serves an Amba Site.

amba functions domains list feed
amba functions domains refresh feed feeds.example.com

DNS and certificate changes are asynchronous. Refresh re-polls both states and may return additional validation records. For externally managed zones it does not modify your DNS. For an active domain bought through Amba, refresh may reconcile the required records automatically and report the publication result.

Limits and temporary claims

Function-domain caps use the project's effective tier (so a comped project uses the enterprise cap):

Attach is also limited to five attempts per project per hour. An unverified hostname is a temporary 24-hour claim and counts toward the project cap. After 24 hours, an exact-host attach retry may reclaim it, but only after Amba rechecks the provider and confirms ownership has not become active. Remove an abandoned claim explicitly if you want to free its project-cap slot sooner.

Pending claims do not consume a Worker route or publish a router KV mapping. Amba allocates those routing resources only after ownership_status becomes active, either during attach or a later refresh.

To detach the hostname:

amba functions domains remove feed feeds.example.com

Detached or unknown hostnames fail closed rather than falling through to another project's function.

MCP tools

Agents can manage the same lifecycle without shelling out:

amba_function_domains_attach({
  project_id,
  name: 'feed',
  hostname: 'feeds.example.com',
});
 
amba_function_domains_list({ project_id, name: 'feed' });
amba_function_domains_refresh({
  project_id,
  name: 'feed',
  hostname: 'feeds.example.com',
});
amba_function_domains_remove({
  project_id,
  name: 'feed',
  hostname: 'feeds.example.com',
});

REST contract

All routes are under /v1/admin and require developer authorization plus project ownership.

Domain rows expose cert_status, ownership_status, the derived live boolean, and additive dns_record_type / is_apex / dns_note guidance. Provider identifiers and raw provider errors are intentionally not part of the customer response.