Create Plugin
A custom provider connects Colotok to a destination that is not built in. Use Provider for a destination that handles one record at a time, or subclass AsyncProvider when a remote service benefits from batches.
AsyncProvider is the preferred base for remote delivery because it already owns the channel, batching threshold, retention policy, flush behavior, and lifecycle. Do not add another queue unless the destination protocol requires a distinct durable store.
Dependencies
Add the core and coroutine artifacts to the custom provider module:
Define a transport boundary
Keep the network library outside the provider's buffering logic. A small interface makes ownership explicit and lets tests use a deterministic fake.
The application can implement this interface with Ktor, OkHttp, or another client. Treat non-success responses as failures by throwing from send; silently swallowing them would make AsyncProvider discard records as if publication succeeded.
Define the configuration
bufferSize is the threshold at which Colotok attempts a batch publish. Its valid range is 1..4096.
Implement the provider
Validate required values in the expression passed to AsyncProvider. This ensures invalid configuration fails before the base class starts its worker.
AsyncProvider manages the buffer and calls onPublish() outside its buffer lock. Let publication errors propagate so the base class can retain the batch for retry.
Use the provider
Delivery and lifecycle contract
These lifecycle rules describe the 1.0.0 API; see Migrating to 1.0 for changes from the published 0.5.0 API.
writeaccepts records only while the provider is open. Logger attributes and MDC have already been snapshotted when the provider receives a record.flush()waits for records accepted before its marker and publishes the provider-specific buffer. It is valid only while the provider is open.close()starts graceful closure without waiting. For graceful shutdown,join()closes when necessary and waits for the worker, final flush, and close hook.forceShutdown()requests cancellation without waiting on any target. Queued records may be lost; no final flush is started. The close hook is invoked once after in-flight cleanup, including when the worker is cancelled before it starts. Code that ignores cancellation can delay closure.forceShutdown(callbackScope, onComplete)notifies after worker termination and resource release. Expected cancellation is success; recorded provider failures are reported in the callback'sResult. Notification-scope cancellation and callback exceptions are separate from provider cleanup. See the completion example.After forced shutdown,
join()waits for cleanup before throwingProviderClosedException. A recorded provider failure takes precedence and is rethrown instead.After graceful or forced closure starts,
flush()throwsProviderClosedException, unless a recorded provider failure takes precedence.
Do not call a provider's own join() or flush() from its onMessage(), onPublish(), onFlush(), or cleanup hooks, including inside withContext(NonCancellable). These waits depend on the same worker and are rejected with IllegalStateException. A hook can request forceShutdown() and return; wait for completion from the application outside that worker. Notification callbacks run after the worker has finished and are not part of the worker's completion condition.
On automatic publish failure, AsyncProvider retains records up to min(bufferSize * 4, 4096) and can retry them on a later publish attempt. At the retention limit it drops the newest incoming record, preserving the older failed batch. A failure during an explicit flush() is propagated to the caller and puts the provider in its failed terminal state; join() reports the same original failure.
Delivery can lose records under buffer pressure or forced shutdown, and retries can duplicate records. If a transport accepts part of a batch and then throws, the complete retained batch can be retried and accepted messages may appear again. Prefer an idempotency key or destination-side deduplication when duplicates matter.
At full retention capacity, the Provider keeps the buffered batch and drops new records. Retry that batch with flush() or graceful shutdown; incoming records do not trigger publication while the buffer is full. A flush failure is reported to the caller and puts the Provider in its failed state. Subsequent lifecycle calls report the original failure.
Implementing IProvider directly
Prefer extending Provider or AsyncProvider to reuse Colotok's cancellation, one-time cleanup, failure preservation, and completion notification. Direct IProvider implementations now need both forceShutdown() and forceShutdown(callbackScope, onComplete); the old no-argument default implementation has been removed. The forceShutdown(onComplete) convenience overload delegates to the explicit-scope overload with the implementation's coroutineScope.
ColotokLoggerContext.addProvider() requires a Provider, so use a Provider subclass for Context integration. A direct IProvider implementation can be used through the interface independently of the Context.
A direct implementation must request shutdown even when the notification scope is already cancelled, and must notify only after its worker and resource cleanup have finished. Repeated requests must not close resources twice or omit a live completion registration just because shutdown has already completed. These guarantees are implemented by the base classes; the interface alone does not provide them. See the IProvider migration notes.
Public extension points
IProvider.channel, job, and coroutineScope, LogRecord.Pin, and Provider.effectiveMetricsCollector remain public in 1.0.0. Use them when implementing or integrating Providers. Application code should use write(), flush(), close()/join(), and forceShutdown() to preserve the lifecycle contract.
The base Provider owns its channel and worker. Sending directly to the channel bypasses the level filter and enqueue metrics; receiving from it consumes records intended for the worker. Closing the channel or cancelling its job/scope directly bypasses the lifecycle entry points. LogRecord.Pin is a flush marker consumed by Provider before onMessage(), rather than a log payload. Handle this type in exhaustive when expressions over LogRecord.
effectiveMetricsCollector is configured when a Provider is added to a Context. Configure metrics through the Context or ProviderConfig.metricsSpec; replacing the effective collector overrides that selection, including any internal metrics collector.
Resource ownership
Decide whether the provider or caller owns its network client:
A client constructed internally should be closed exactly once from
onClosed().An injected client is usually caller-owned and should not be closed by the provider.
Lazy initialization prevents an unused provider from opening resources merely because it is closed.
Document the chosen ownership rule in the configuration API. Avoid guessing ownership from the client type.
Testing
Test the provider through a fake WebhookSender rather than a live network endpoint. At minimum, verify:
formatting and record order in a successful batch;
failure propagation from
onPublishand retention until a later retry;graceful
join()performs the final publish;forced shutdown returns without waiting for in-flight cleanup, and completion is notified only after owned resources are released, including cancellation before worker start;
injected resources remain caller-owned;
invalid configuration fails before creating a worker or network client.
Also test the transport adapter separately for request encoding, authentication, non-success responses, timeouts, and client closure.