Cal.diy connector configuration

This reference describes the configuration accepted by aip-host-cal-diy at the reviewed source revision. A complete process combines eight Cal.diy-specific settings with the shared connector-host bootstrap contract.

All settings are read at startup except the optional credential-revision policy file, which is re-read before provider side effects. Provider credentials, webhook secrets, destination prefixes, and other startup settings are not documented as hot-reloadable.

Configuration identity

Each field is available through the listed environment variable. Cal.diy fields also expose the listed command-line flag. Shared fields use the equivalent kebab-case connector-host flag. Use one source of truth per setting so an orchestrator and a manual override cannot silently disagree.

Secret values belong in files. Environment variables and command-line flags name those files or carry non-secret identity and policy values.

Cal.diy-specific settings

Authentication groups

Exactly one provider authentication group must be complete:

Bearer = AIPD_CAL_DIY_BEARER_TOKEN_FILE

or:

Cal platform client = AIPD_CAL_DIY_OAUTH_CLIENT_ID
                    + AIPD_CAL_DIY_OAUTH_CLIENT_SECRET_FILE

The Bearer setting conflicts with both client settings. A partial client pair also fails startup. The provider client sends either Authorization: Bearer … or the x-cal-client-id and x-cal-secret-key headers. It performs no browser OAuth flow, token exchange, or refresh.

Base URL

The base URL parser requires:

• an https URL with an authority; or
• http only when the host is a loopback name or address;
• no username or password;
• no action-selected origin.

The parser removes query and fragment components, normalizes the trailing slash, and refuses redirects. The provider request timeout is fixed at 30 seconds.

Account id

The account id must contain 1 through 128 ASCII letters, digits, dots, underscores, or hyphens. It scopes the durable Cal.diy mutation ledger together with the normalized base URL.

For a standalone deployment, make it equal to the shared AIP_CONNECTOR_HOST_EXTERNAL_ACCOUNT_ID by deployment policy. The reviewed code validates both fields but does not promise to compare them automatically.

Webhook settings

Webhook ingestion is disabled when no secret mappings are configured. When one or more mappings are present, the host adds this route:

POST /webhooks/cal-diy/{subscription_id}

It also requires AIP_CONNECTOR_HOST_EVENT_ENDPOINT; startup fails if the host cannot construct its central event publisher.

Secret mappings

Each mapping has the form:

bookings-primary=/run/secrets/cal-diy-webhook-bookings

The reference before = must:

• contain 1 through 128 ASCII bytes;
• start with an ASCII letter or digit;
• contain only letters, digits, ., _, ~, or -;
• be unique in the host configuration.

The path after = must name a non-empty owner-controlled secret file. The host reads at most 16 KiB from each file. Do not use a comma in the reference or path when the environment variable’s comma-delimited form is used.

Subscriber prefixes

Each prefix must be an absolute credential-free HTTPS URL with a host and no query or fragment. A missing trailing slash is normalized. Duplicates are removed.

For a provider webhook create or update, the candidate URL must have the same scheme, host, effective port, and an exact path made from the prefix plus the operation’s trusted subscription selector. An empty prefix list denies every provider webhook destination.

Secret mappings control inbound verification. Subscriber prefixes control provider webhook creation. Configuring one does not automatically configure the other.

Fixed webhook bounds

These values are source constants, not environment settings.

Shared process and endpoint settings

For each peer DID, configure the inline value or file, not both. Both peers are required. A DID must parse to a usable verification key.

Public and control endpoints require HTTPS, have no embedded credentials, query, or fragment, and use their exact protocol paths. The loopback exception is a development boundary; enabling it on a non-loopback bind fails startup.

Durable storage and replica identity

The database schema and durable state must belong to this connector boundary. Changing an artifact, contract, account ownership, or replica identity without updating its admission and configuration identity is not a dynamic setting.

Tenant and external account settings

External account id and system must be configured together or omitted together. A normal Cal.diy instance sets the system to cal_diy and binds one tenant to one account-specific host.

Trust, topology, and secret-provider identity

Region, zone, and capacity class affect declared topology. They do not move a process, configure a network, or increase the local concurrency limit.

The secret-provider reference is not the Cal.diy credential. The standalone binary reads the actual provider secret from its Cal.diy-specific file.

Credential identity and revocation settings

Id, issuer, at least one scope, and revision must be configured together or all omitted. For Cal.diy, the stable logical issuer is cal_diy_deployment and operation scopes use cal_diy:<operation-suffix>.

If a policy file is set, it must authorize the configured revision at startup and whenever it is re-read before a provider side effect. Without a file, the host constructs a static policy authorizing the configured current revision.

Callback and event delivery settings

Both dispatchers use the host signing identity and the configured private TLS root when present. Network exceptions are explicit; setting an exception without its endpoint fails startup.

Lifecycle and resource limits

Manifest size, capability count, and native request-body limits also exist in the common host but are fixed by this binary rather than exposed as Cal.diy settings.

File requirements

The reader checks metadata before and after opening a file and, on Unix, rejects an inode or device change during that operation. It rejects empty or oversized files before parsing them.

Fixed provider versions

The connector selects versions per operation family. They are not deployment settings.

Changing a Cal.diy upstream revision may require different route versions. Do not override these values outside a source, schema, test, and qualification change.

Configuration supplements

These examples show only Cal.diy additions. They are not complete host or production configurations and intentionally contain no secret value.

Static Bearer account

AIPD_CAL_DIY_BASE_URL=https://cal.example.test
AIPD_CAL_DIY_ACCOUNT_ID=calendar_primary
AIPD_CAL_DIY_BEARER_TOKEN_FILE=/run/secrets/cal-diy-provider
AIPD_CAL_DIY_MAX_RESPONSE_BYTES=8388608

Cal platform client headers

AIPD_CAL_DIY_BASE_URL=https://cal.example.test
AIPD_CAL_DIY_ACCOUNT_ID=calendar_primary
AIPD_CAL_DIY_OAUTH_CLIENT_ID=client_public_id
AIPD_CAL_DIY_OAUTH_CLIENT_SECRET_FILE=/run/secrets/cal-diy-provider

Signed webhook ingress and creation

AIPD_CAL_DIY_WEBHOOK_SECRET_FILES=bookings-primary=/run/secrets/cal-webhook-primary
AIPD_CAL_DIY_WEBHOOK_SUBSCRIBER_PREFIXES=https://aip.example.test/cal/webhooks/
AIP_CONNECTOR_HOST_EVENT_ENDPOINT=https://aip.example.test/aip/v1/connector-events

The provider destination for selector bookings-primary must then be exactly https://aip.example.test/cal/webhooks/bookings-primary. Deployment ingress must forward that path to the host’s /webhooks/cal-diy/bookings-primary route; the connector does not configure the external reverse proxy.

Startup and reload behavior

Startup proceeds in this order:

1. parse Cal.diy and common host settings;
2. read and validate one provider authentication group;
3. construct the fixed Cal.diy client and account boundary;
4. apply the provider response bound and webhook destination policy;
5. validate host identity, peer trust, files, endpoints, and credential policy;
6. discover the source-derived manifest without provider I/O;
7. open the PostgreSQL runtime stores and bind Cal.diy durable state to them;
8. configure webhook secrets, replay state, route, and event publisher when enabled;
9. start the host lifecycle, registration, readiness, and request server.

Readiness includes durable storage and connector-local provider health. A syntactically valid configuration can still remain unready because admission, registration, storage, TLS, DNS, or the provider profile request fails.

Configuration failures

Related documentation

• Configure authentication and tenant routing
• Cal.diy connector overview
• Shared connector-host configuration
• Environment variables
• Deploy the connector fleet