Events

lacme.events

Event system for lacme observability.

Provides typed event dataclasses and a centralized :class:EventDispatcher for subscribing to certificate lifecycle events. Events are also logged via stdlib :mod:logging with structured extra fields.

CACertificateIssued dataclass

Emitted when the CA signs a new certificate.

CertificateAuthorityInitialized dataclass

Emitted when a CA root certificate is created or loaded.

CertificateExpiring dataclass

Emitted when a certificate is approaching its expiry threshold.

CertificateIssued dataclass

Emitted after a certificate is successfully issued.

CertificateRenewed dataclass

Emitted after a certificate is successfully renewed.

ChallengeFailed dataclass

Emitted when an ACME challenge validation fails.

EventDispatcher

Central event bus for lacme lifecycle events.

Supports both sync and async subscribers. Thread-safe for use with :class:~lacme.sync.SyncClient.

Example::

dispatcher = EventDispatcher()
dispatcher.subscribe(lambda e: print(e), event_type=CertificateIssued)
await dispatcher.emit(CertificateIssued(...))

emit async

emit(event: Event) -> None

Emit event: log it, then invoke all matching subscribers.

Both sync and async callbacks are supported. If a sync callback returns an awaitable, it is awaited. Exceptions in callbacks are caught and logged — they never propagate to the caller.

For synchronous contexts, use :meth:emit_sync instead, which skips async callbacks entirely (with a warning).

emit_sync

emit_sync(event: Event) -> None

Emit event from synchronous code.

Callbacks detected as coroutine functions (via :func:inspect.iscoroutinefunction) are skipped with a warning. Unlike :meth:emit, this method does not await return values. If a sync callback accidentally returns a coroutine, it is closed to prevent un-awaited coroutine warnings and a warning is logged.

subscribe

subscribe(callback: Callable[..., Any], event_type: type[Event] | None = None) -> None

Register callback for events of event_type, or all events.

unsubscribe

unsubscribe(callback: Callable[..., Any]) -> None

Remove callback from all subscription lists.

RateLimitWarning dataclass

Emitted when certificate issuance is approaching a rate limit.