Built-in Events

Use this catalog to find the notification for an operation you want to observe. Topic variables belong to the named package; payload names below are relative to that package. A signal has no data and its listener takes event.Void. Writing Listeners covers registration and ownership.

Publishing Policies

Apart from application lifecycle and health events, components publish nothing without an explicitly configured bus. Configure Events when constructing the component. With mail imported from arkoren.dev/core/service/mail, an existing mail driver, and the shared bus:

mailer := mail.New(driver, func(mailer *mail.Builder) {
	mailer.Events(bus)
})

The setting enables notifications, not subscriptions. Components use best-effort Emit: callbacks run synchronously, and their errors or panics are logged without replacing the operation result. Failure stops delivery to later listeners. Slow listeners delay the operation. Events stay in the publishing process, are not retried, and can be lost on a crash—even if a listener would enqueue work. Required records belong at an application-owned durable boundary.

Payload omissions are not universal redaction. Some events retain raw errors, identifiers, or diagnostic stacks; contexts retain caller values. Select safe attributes instead of dumping a payload, context, or returned error chain.

Application

The application always publishes on app.Events(). Register before Start or during synchronous composition; a startup callback is too late for Starting.

Stopped does not mean cleanup succeeded: inspect the lifecycle method’s returned error. The application is still stopping while that callback runs. Failed excludes later cleanup and telemetry-finalization errors. Composition or telemetry startup failure can publish Failed without Starting. Failed and Stopped use contexts detached from cancellation.

Failing lists check names in registration order; do not mutate the shared slice. Check errors and startup errors are raw diagnostics, not safe external text. See Lifecycle and Ownership and Health and Readiness for operating policy.

HTTP

HTTP Events owns the exact publication conditions, payloads, and privacy limits for server lifecycle, recovered panics, outgoing requests, CSRF/rate-limit/content-type rejections, sessions, signed links, and webhook receipts. Enable each component separately; setting a server’s bus does not implicitly enable every middleware’s events.

Authentication and Authorization

These notifications observe refusal, not successful identity establishment:

Rule is the zero-based rule index in registration order. Method is empty for Gate.Authorize, which has no request. Neither payload contains a path, user, or cause. Rule errors, missing users, allowed calls, and the free gate.Authorize/gate.Require functions publish no gate event. Identity login/logout methods also have no bus and publish nothing themselves.

Each refusal publishes, even when a custom error response changes the default status. Clients control the frequency: keep callbacks cheap and place rate limiting before these checks. Methods are client-controlled too; keep secrets out of custom method names. See Authentication and denial monitoring.

OAuth Outcomes

The client in arkoren.dev/driver/oauth/oauthauth uses ClientBuilder.Events:

Callback rejection covers invalid/replayed login cookies, provider errors, missing codes, exchange/token-check failures, and local login failures. Configuration and missing-session exits before cookie consumption publish nothing. Login/logout events describe request-local mutation, not durable session persistence or provider logout.

LoginFailedEvent.Err is only ErrInvalidCallback, ErrProviderUnavailable, or an opaque local-login classification with no exported sentinel or cause. Match the two exported classes with errors.Is; do not classify opaque errors by text. TokenRejectedEvent.Err is a fixed opaque error with no exported sentinel or native cause. Count that outcome rather than trying to unwrap diagnostics.

ProviderError admits only invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, or temporarily_unavailable; absent or unknown hints become empty. It remains an untrusted callback hint, not an authenticated diagnosis. Callback and Verify return errors with original causes separately; those causes can expose credentials or claims. Subject and Issuer can identify a person even without email or tokens. See OAuth Login for configuration.

Database

With database.Builder.Events, outermost transactions publish database.TransactionCommitted (database.transaction.committed) or database.TransactionRolledBack (database.transaction.rolled-back). Both carry TransactionEvent{System, Namespace, Err}. Nested joined transactions publish nothing independently.

A confirmed commit publishes nil Err before after-commit hooks; later cleanup or hook errors can still return database.ErrAfterCommit. Before confirmed commit, body/context/commit failures publish rollback. A body error bearing ErrAfterCommit still requests rollback. Panics propagate without a transaction event. Committed-event listeners run outside the finished transaction. See Transactions and Query Monitoring.

With migrate.Builder.Events, each handled migration carries MigrationEvent{ID, Group, Batch, Rollback, Duration, Err}:

Group is empty for application migrations. A confirmed commit followed by cleanup failure still publishes the completed outcome with nil payload Err; the returned error stops the run. Raw database errors can contain sensitive data. Migration procedures stay in Migrations.

Feature Flags

feature.Builder.Events enables feature.EvaluationFailed (feature.evaluation.failed), carrying EvaluationFailedEvent{Key, Err} when driver evaluation fails and the caller receives its default plus the error. The error retains the driver’s cause, wrapped with the flag key. Subject, attributes, and values are omitted.

Successful/off evaluations, invalid definitions or subjects, and facade type conversion failures publish nothing. Every driver failure publishes, including hot-path misses. See Feature Flags.

Search

search.Builder.Events enables administrative Sync/Drop observations: search.Synced, search.Dropped, and search.Failed. Queries and document writes publish nothing. Search outcomes give their canonical names, bounded payload, and partial-effect limits.

File Storage

With storage.Builder.Events, successful facade changes publish:

Store is the configured name or default. Deleting an absent object also succeeds, so the notification does not prove prior existence. Reads, listings, failed writes, and direct signed-URL uploads publish nothing. Object metadata and keys can identify resources. See storage monitoring.

Secrets

secret.Builder.Events enables secret.MutationSucceeded and secret.MutationFailed for facade Put, Update, and Delete results. Secret outcomes define their payload and names. Reads and external/native writes publish nothing; these are not rotation or rollout records.

Queues

Enable queue.ConsumerBuilder.Events on the consumer. Payloads share ID, Name, Queue, and the driver’s delivery count Attempts (zero if unavailable):

Terminal failure covers permanent/exhausted errors, undecodable payloads, and unknown names after their attempt limit. If settlement fails, no settlement notification fires; the error returns through consumption and the broker outcome remains unconfirmed. If the driver’s Consume returns an error, Consumer.Run cancels its other queue consumers, waits for them to stop, and returns the first error. Accepted settlement does not prove durable failed-job storage.

Delay is the requested retry delay, not an exact execution time. Exhausted retries, shutdown release, and driver-controlled unknown-name redelivery do not publish JobRetried. A timeout can be followed by retry, failure, or rejection for the same delivery; settlement failure can prevent that follow-up. Success after the deadline publishes no timeout event. Errors retain diagnostics; payload bytes are omitted. See Consuming Jobs.

Broadcasting

broadcast.ConsumerBuilder.Events enables broadcast.ListenerFailed (broadcast.listener.failed), carrying ListenerFailedEvent{ID, Name, Err} once per listener that returns an error, fails decoding, or panics. Several listeners can fail one delivery and publish in listener order. ID can be empty. Success publishes nothing; transport settlement is not the observation. Payload and metadata are omitted, but errors retain causes. See broadcast delivery.

Mail

With mail.Builder.Events, mail.Sent (mail.sent) carries SentEvent{Receipt, Recipients, Attachments} after driver acceptance; mail.Failed (mail.failed) carries FailedEvent{ErrorClass, Recipients, Attachments} after returned validation or driver failure. Counts omit addresses and contents; the receipt is a provider submission identifier, not a delivery receipt.

Failure classes are context.Canceled, context.DeadlineExceeded, mail.ErrInvalidMessage, then error, in that priority order. No native cause or diagnostic text enters FailedEvent; Send returns the original error separately. Nil-context rejection and driver panics publish neither outcome. Acceptance is not recipient delivery, and failure does not rule out remote acceptance. See mail monitoring.

Push Notifications

push.Builder.Events enables push.Accepted and push.Failed for returned submission results. Push outcomes give their names and payload; neither confirms device delivery or display.

Payments

payment.Builder.Events enables payment.OperationCompleted and payment.OperationFailed for driver-returned facade calls. Payment outcomes give their names and bounded payload; neither is a settlement or fulfillment event.

Scheduled Tasks

Enable schedule.Builder.Events for run outcomes and deferred-task requests:

Driver-started runs and RunNow both publish run outcomes. Task distinguishes deferred tasks from entries; task payloads are omitted. A skip is not a failure, and a driver’s overlap guard preventing invocation is not an execution skip. Failure errors can include recovered panics and timeout errors; returning nil after a deadline still succeeds. Driver retry policy is separate.

TaskDeferred reports acceptance, not task completion. Canceling an unknown or finished ID can succeed and publish too; it does not prove removal or that a running handler stopped. See failure events and deferred tasks.

Workflows

Enable workflow.ClientBuilder.Events on the client:

Failures, including already-started runs, publish nothing. Canceling a finished run succeeds and publishes. These are local client actions, not subscriptions to engine completion or proof a signal was consumed. Input, output, signal values, and metadata are omitted; run IDs remain potentially identifying data. See workflow observations.

Language Models

Use llm.ModelBuilder.Events for model/agent/tool events and llm.EmbedderBuilder.Events for embeddings:

Each topic has its correspondingly named …Event type. Payloads describe model/agent/tool names, usage or counts where relevant, and duration—not prompts, replies, arguments, vectors, or raw errors. Steps counts model turns, not tool calls. Agent turns do not also publish standalone response events. Abandoning a stream, even by breaking at standalone Done, suppresses its final outcome.

Response, embeddings, and agent failure payloads carry bounded ErrorType: context cancellation/deadline names first, then known llm sentinel names, otherwise unknown. Policy failures use llm.ErrToolAvailability ahead of ErrPermanent unless a context error matches. Tool failure carries no error field. Original returned/yielded errors retain diagnostic causes and need a separate privacy review. See observing calls.

For registration and dispatch, see the event API reference.