Deploy native HTTP with TLS and CA trust

Select the native host and sources

Native only, published ASPL 0.7.0. Follow native installation and verify aspl --version prints aspl 0.7.0. The host must be x86-64 Linux with glibc 2.34 or later, /lib64/ld-linux-x86-64.so.2, libc.so.6 and libm.so.6. The installed tool includes the supplied HTTP declarations and prepared native templates with private static HTTP dependencies. No separate HTTP backend package, OpenSSL runtime or C compiler is required. OpenSSL and curl are host tools for the local exercise below.

Use the HTTP guide for handlers and sessions and the API reference for exact aliases, signatures and bounds. The browser playground and private embedding profile reject HTTP imports before execution. The earlier raw deployment download (opens in a new tab) keeps its earlier release scope; these instructions cover 0.7.0.

Create a working directory named http-work with separate ar and en source directories. Download the desired supplied variants and their matching modules from these stable families:

Family pages own exact source/module downloads and expected outcomes. There are no bundled TLS assets or input lines. Keep the original filenames and bytes; configuration edits below apply to separate copies. Run every command below from http-work, including commands that name a source under ar/ or en/. Source imports resolve beside the importing file; relative TLS paths resolve from the process working directory.

Configure before networking

http::runtime_config() returns execution-wide defaults. Call http::configure before the first validated network attempt. To lower outbound capacity to 8, also lower idle_client_connections to at most 8; its default is 16. The limits family checks the invalid combination and its correction. See runtime fields and configuration rules.

ClientOptions carries per-request message limits, deadlines, redirect/gzip flags and trust selection. ServerConfig carries listeners, message limits and deadlines. Options and serving configuration are copied for the operation. Numeric settings reserve no memory or sockets, and Linux limits or available memory can still prevent admission.

A validated network attempt freezes runtime configuration even when connection or TLS startup fails. One validated serve or start attempt consumes the execution's serving slot. A later configure/start attempt returns http.already_started; correct startup material and start a new process. Pure validation errors leave configuration and the serving slot available. Port 0 is invalid. IPv6 listeners are IPv6-only; use separate IPv4/IPv6 listeners for explicit dual stack.

Select CA trust

Default ClientOptions has use_private_ca=false and an empty ca_file. On first HTTPS use, before connection, 0.7.0 selects the first existing path in this order:

1. /etc/ssl/certs/ca-certificates.crt
2. /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
3. /etc/ssl/cert.pem
4. /etc/pki/tls/certs/ca-bundle.crt
5. /etc/ssl/certs/ca-bundle.crt

An existing unreadable, empty, malformed or oversized selected store gives http.ca_load_failed. It does not try a later bundle. Discovery errors other than a missing path also fail. SSL_CERT_FILE and SSL_CERT_DIR do not override this search. Provision a usable PEM bundle using the host's CA administration tools; setting an environment variable is not a repair.

When all five bundles are absent, the native contract scans /etc/ssl/certs/ in byte-name order, following links to regular files and deduplicating device/inode pairs. Nonregular entries are ignored. The isolated 0.7.0 fixture verifies this directory-only case; an empty, unreadable or malformed directory store still fails with http.ca_load_failed. Do not assume an arbitrary host certificate directory is usable. The TLS reference lists the scanning and material limits.

For an explicit private PEM CA, set use_private_ca=true and ca_file to its readable path. This replaces default trust; it never adds the host store or disables verification. A false flag requires an empty path; a true flag requires a nonempty path. A private CA can work even when the default store is unusable. Successfully parsed trust stays pinned for that execution. Restart after changing CA files.

TLS 1.2/1.3 clients verify chain, dates and DNS/IP SAN identity. Common Name alone is insufficient. DNS wildcards cover one leftmost label; an IP URL requires a matching IP SAN. An unrelated but valid CA or wrong SAN gives http.tls_verify_failed, distinct from a CA loading failure. These checks do not affect offline check/build or plain HTTP.

Prepare and run direct TLS locally

For this loopback exercise, create a two-day self-signed RSA certificate and unencrypted matching key. The certificate is also the explicitly selected trust anchor. Generate them in http-work:

openssl req -x509 -newkey rsa:2048 -nodes -days 2 \
  -subj /CN=localhost \
  -addext 'basicConstraints=critical,CA:TRUE' \
  -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \
  -keyout server.key -out server.pem
chmod 600 server.key
aspl check en/direct-tls.aspl
aspl build -o tls-service en/direct-tls.aspl
./tls-service

For Arabic source, replace en/direct-tls.aspl with ar/اتصال-مشفر-مباشر.لبات. Reserve port 8443. The process stays in the foreground without output. In a second terminal in the same working directory:

aspl check en/client-tls.aspl
aspl run en/client-tls.aspl
curl --silent --show-error --http1.1 --cacert server.pem \
  --request POST https://localhost:8443/stop

For Arabic source use ar/عميل-مشفر.لبات. The client prints checked text, JSON, 00 FF 41, and 404 without a trailing newline and returns 0. The verified POST has an empty body and drains the service, which returns 0. HTTP 404 is successful response data, not a transport failure.

For deployment, supply the application's PEM certificate chain and matching unencrypted key, readable by its service account. Each listener loads one chain/key at startup, checks their match and does not reload renewed files. Restart with new material. Supported key families and exact limits remain in TLS inputs. SNI-based server certificate selection and client-certificate authentication are excluded.

Verify a handler's upstream request

Copy the selected direct-TLS root and its matching modules to upstream/. Change only that copy's TLS port in settings.aspl from 8443 to 9443. The Arabic field is منفذ; the English field is port. Leave the original downloaded files unchanged. From http-work, start the upstream in its own terminal:

aspl check upstream/direct-tls.aspl
aspl build -o upstream-service upstream/direct-tls.aspl
./upstream-service

Start the unmodified plain service in another terminal:

aspl check en/service.aspl
aspl build -o plain-service en/service.aspl
./plain-service

For Arabic source use ar/خدمة.لبات. Both services find server.pem and server.key in http-work. From a third terminal:

curl --silent --show-error --http1.1 http://127.0.0.1:8080/upstream

The response is 200 with مرحبا من ASPL. The plain service's copied app::Config fixes the upstream URL https://localhost:9443/hello and private CA server.pem. Its handler reads that configuration and makes a context-bound child request. To deploy with another peer, edit the root's configuration in a copy, then check and rebuild it. HTTPS service certificates and outgoing CA trust are independent inputs.

With the parent live, a missing or malformed CA produces 502 with http.ca_load_failed; a valid unrelated CA produces 502 with http.tls_verify_failed; a stopped peer produces 502 with http.connect_failed. Observe each in a fresh process because loaded trust is pinned. A child deadline can produce http.timeout. Parent expiry or detected disconnect cancels the handler and discards late results and publication. The sample forwards only status and body bytes, not stale peer Content-Length/Content-Encoding metadata. There is no automatic retry or rollback of peer effects.

With the upstream still running, aspl run en/default-trust.aspl succeeds only if the host trusts its certificate. For the untrusted local certificate it prints http.tls_verify_failed and returns 1; absent or unusable host trust instead gives http.ca_load_failed. Do not install this exercise certificate into the machine trust store merely to run the private-CA workflow.

Stop the plain and TLS upstream services with verified requests:

curl --silent --show-error --http1.1 --request POST http://127.0.0.1:8080/stop
curl --silent --show-error --http1.1 --cacert server.pem \
  --request POST https://localhost:9443/stop

Put plain HTTP behind an existing proxy

An existing reverse proxy can terminate public TLS and forward HTTP/1.1 to the plain service on 127.0.0.1:8080. Configure its public listener, certificate renewal, limits and timeouts separately. For nginx, the forwarding location is:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Connection "";
}

ASPL sees a plain connection from the proxy. Forwarded scheme/address headers are ordinary application data and do not change IncomingRequest::tls, routing or authority. Define which proxy you trust before using those headers for security decisions. The sample /stop endpoint has no authentication; remove it or restrict access before exposing an application. This snippet does not provision a proxy or make the loopback exercise a public service.

Relocate the generated programs

Build before relocation. aspl check and aspl build are offline and do not start listeners, read CA material, load declared application C libraries or invoke a C toolchain. Any HTTP import in the module graph selects the HTTP native template, even if unused.

Copy the generated tls-service, plain-service or upstream-service executable to the target host. Start it from the intended working directory with its required TLS files. The ELF includes the checked module graph and VM, so neither ASPL nor the source/helpers are required there. Host loader/system libraries, application certificate/key/CA files and any declared C shared libraries remain external dependencies. Executables accept reserved diagnostic/color options; arbitrary application arguments do not configure these examples.

./tls-service --aspl-diagnostic-language=en --aspl-color=never

Choose a service account that can read the key and bind the configured address/port. Keep the key restricted, use a working directory with the intended files, and restart after certificate renewal or configuration changes. The loopback sample ports need no privileged-port setup. See native host requirements and generated program commands.

Diagnose startup and shutdown

Startup is all-or-nothing. A later listener failure releases earlier listeners and allocations before returning a recoverable failure. The service roots print the stable code without a newline and return 1; use the full error reference for distinctions.

POST /stop requests drain and normal return 0. First SIGINT/Ctrl+C or SIGTERM drains and ends with status 7; a second signal skips remaining drain. Terminal traps keep status 5, not an automatic 500. The 10 ms poll/wake value is a responsiveness target, not a real-time host guarantee. See shutdown and cancellation.