Module lifecycle

public interface IModule
{
    Task Start();
    Task Stop();
}

public interface IConfigurableModule : IModule
{
    Task<IConfigurablePage[]> GetConfigurablePages();
}

​

Ownership rule

[Singleton]
public sealed class ExampleModule : IModule
{
    private QueueWebService? endpoint;

    public Task Start()
    {
        HttpAuthenticationScheme[] schemes = HttpModule.GetAuthenticationSchemes();
        this.endpoint = new QueueWebService("/ExampleQueues", schemes);
        Gateway.HttpServer?.Register(this.endpoint);
        return Task.CompletedTask;
    }

    public Task Stop()
    {
        if (this.endpoint is not null && Gateway.HttpServer is not null)
            Gateway.HttpServer.Unregister(this.endpoint);

        this.endpoint = null;
        return Task.CompletedTask;
    }
}

​

Start safely

1. Validate configuration without logging secrets.
2. Create dependencies that do not publish work.
3. Register routes, stanza handlers, event sinks, and runtime services.
4. Start background loops last.
5. If any step fails, unwind already-created resources before rethrowing.

​

Stop safely

1. Stop accepting new work or unregister ingress.
2. Cancel background loops.
3. Await in-flight tasks with a bounded policy.
4. Flush durable state and queues.
5. Unregister handlers, routes, event sinks, and timers.
6. Dispose owned dependencies.

​

Runtime inventory

• avoid two discoverable implementations claiming the same route/name/namespace;
• make discovered types concrete and constructible according to the consuming subsystem;
• use [Singleton] only when one shared instance is correct;
• expect adding an assembly to change inventory results globally;
• test startup with the same assembly set as production.

​

Failure visibility