Writing services for MariaServiceHoster

This page summarizes how to write a new service for MariaServiceHoster. Services run as standalone child processes behind the host's reverse proxy.

See the complete service authoring guideline for contracts, configuration and integration details (repository access required).

Service design

• Produce a standalone executable that starts from its own installation directory.
• Keep the service independent of MariaServiceHoster. The host owns public listeners, routing, process supervision and monitoring.
• Honor configurable listener addresses, protocols and Settings:PathBase; do not hard-code public hostnames, ports or route prefixes.
• Support orderly shutdown where possible.
• Keep dependencies, storage paths and other service-specific settings explicit.

The recommended reference implementation is Src\Hosts\ReferenceSampleService. Internal repository setup helpers are not required dependencies for customer-developed services.

Health and readiness

Provide lightweight HTTP endpoints:

• GET /health — return HTTP 200 and a compact JSON status response when the service is healthy.
• GET /ready — return HTTP 200 when ready to accept traffic, or HTTP 503 while unavailable. The host uses this endpoint to validate startup.

Both endpoints must work under the configured path base. Keep probes inexpensive and avoid returning sensitive information.

Configuration

The host supplies service-specific configuration in three sections: Logging, Kestrel and Settings.

The default transport uses environment variables prefixed with MARIA_HOSTED__. File-based transport passes a generated configuration file using --config. Implement the transport selected for the deployment and ensure host-provided values take precedence over standalone defaults.

This child-service configuration contract is separate from the command-line convention used to start MariaServiceHoster itself.

HTTP, Swagger and gRPC

For HTTP APIs, support Settings:UseSwagger and expose:

• /swagger/v1/swagger.json
• /swagger/index.html

Ensure generated URLs and Swagger work under the configured path base. Each service owns its API description; the host provides discovery rather than merging service documents.

For gRPC, prefer a separate internal HTTP/2 listener and a distinct external route prefix. Coordinate routing with the host configuration.

Packaging and integration

Ship the complete published payload with a maria-service-manifest.json containing package identity, executable name, version, executable SHA-256 and a startup probe path such as /ready.

Generate the hash from the final executable during packaging. Supply a detached manifest signature when required by host trust policy.

Installation alone does not register the service: host configuration must also declare its package location, service settings, backend listeners and proxy exposure. See Custom MariaServiceHoster service installer for packaging guidance.

Before integration, verify standalone startup, configuration overrides, path-base handling, health/readiness, API documentation and shutdown. Then verify startup and routing through the host.