Skip to main content

Service configuration

A service configuration is the composition root for one locally runnable emulator. It names the service, selects one OpenAPI source, defines its listener, and optionally imports or contains HCL behavior declarations. simile register validates and compiles the complete configuration before installing it, while simile start --config retains the direct, unregistered path.
The document must contain exactly one service block. Its label is the service name passed to the CLI:
--port has invocation precedence over listen.port; it does not edit the configuration.

Local registry

The default registry root is $HOME/.simile; SIMILE_HOME overrides it for CI and tests. A registration is an immutable runtime snapshot:
The copied HCL preserves the registered source for inspection. The versioned JSON manifest records listener and provenance metadata. The deterministic .similec artifact is the runtime authority. Consequently, starting a registered service neither depends on the original config path nor refetches a URL-based OpenAPI source. simile update NAME recompiles the stored HCL after reloading the OpenAPI and imported behavior sources it names. simile update NAME --config URL_OR_FILE first replaces that HCL source. The fetched HCL is kept in the installed revision; it is not saved as a separate download. Compilation completes before current advances, so a failed update leaves the previous revision active. Existing revisions remain available for recovery, while current is the only mutable pointer. register --force remains an explicit replacement path, but normal refreshes should use update. locks/ is reserved for cross-process coordination as registry operations expand; tmp/ contains only same-filesystem staging directories used before an atomic revision install. state/ is deliberately outside revisions so future emulated resource state can survive a service update.

Listener

listen.port is required and must be an integer from 1 through 65535. listen.host is optional and defaults to the loopback address 127.0.0.1. The host must currently be an IP address rather than a DNS name. Binding a public interface is therefore a deliberate configuration choice, not a CLI default.

OpenAPI source

The openapi block must contain exactly one source:
or:
A relative path is resolved from the directory containing the service configuration. A URL is read into memory for compilation and is not saved to disk. Both simile register --config and simile update --config can load the service configuration itself from an HTTP or HTTPS URL. Because that document has no local directory, it must use an OpenAPI URL and inline behavior declarations. Relative OpenAPI and imported behavior paths in a remote configuration are rejected rather than resolved against the process working directory.

Behavior modules

behaviors is an optional list of HCL module paths. Relative paths resolve from the configuration directory. The service document may also contain the existing resource, async, and behavior blocks after the service block:
Resources are the portable dependencies of the emulated service. They name abstract capabilities such as db, cache, queue, mail, object_store, event_bus, scheduler, or http, never a production vendor. Async declarations connect observable follow-up work to those capabilities. Imported and inline declarations enter the same semantic compiler. Duplicate declarations, unknown OpenAPI operation IDs, undeclared resources, and contradictory response selections fail startup before the listener binds.

Current HTTP boundary

The server compiles OpenAPI routes into a route table and delegates matched operations to the protocol-neutral runtime. It currently provides:
  • literal and {parameter} path-template matching, with literal routes taking precedence;
  • 404 Not Found and 405 Method Not Allowed responses at the transport boundary;
  • an 8 MiB request-body limit;
  • JSON request-body decoding and compiled-schema validation through the runtime;
  • generated OpenAPI response status, media type, and body;
  • named OpenAPI and HCL outcomes, including an optional process-wide --scenario NAME;
  • service-declared protocol-error mappings for malformed or contract-invalid requests, with a Simile diagnostic only when the operation has no suitable error response;
  • process-local replay for Idempotency-Key and for the full URI of GET requests; and
  • one-line access logs containing method, path, status, TCP peer IP, user agent, request content type and size, response content type and size, and elapsed microseconds; and
  • graceful shutdown on Ctrl-C.
Access logs are emitted to stderr at info level by default for simile start. Pass --quiet to disable them, or use SIMILE_LOG to select a tracing filter explicitly. The origin is the accepted socket’s peer IP; Simile does not trust forwarding headers. Request and response bodies, query strings, credentials, idempotency keys, and header values other than User-Agent are never written to the access log. Path, query, and header schema validation are not yet compiled into the runtime artifact. Form and multipart codecs are also not yet implemented. HCL-declared asynchronous operations are returned by the runtime as plans, but the server does not yet execute abstract resources or persist durable service state. These omissions are reported here so that starting a service is not mistaken for full behavioral fidelity.