Package io.github.pimak.ntfy.quarkus.runtime

Interface NtfyRuntimeConfig

@ConfigMapping(prefix="quarkus.ntfy") @ConfigRoot(phase=RUN_TIME) public interface NtfyRuntimeConfig
Run-time configuration surface for the ntfy Quarkus extension, mapped from the quarkus.ntfy.* config namespace.

Declared as a ConfigMapping interface (the Quarkus 3.37 idiom — the legacy @ConfigItem field style may not be mixed with mappings in the same module) and marked ConfigPhase.RUN_TIME so every value — including the endpoint url/topic and the credentials — is read when the application starts, never baked into the build. This is what keeps the extension native-image-safe: no HTTP client or thread is created at build/static-init time.

Durations are surfaced as raw Strings and parsed via DurationParser in the recorder/producer, so the flexible ntfy spellings ("5s", "3m", "500", "PT5S") all work rather than being constrained to Quarkus' own duration converter.

  • Method Details

    • url

      Optional<String> url()
      Base URL of the ntfy server, e.g. https://ntfy.sh. Alerting is inactive when unset.

    • topic

      Optional<String> topic()
      Topic to publish to. Alerting is inactive when unset.

    • token

      Optional<String> token()
      Bearer/access token (ntfy tk_...); takes precedence over username/password.

    • username

      Optional<String> username()
      Basic-auth username (used with password() when no token() is set).

    • password

      Optional<String> password()
      Basic-auth password.

    • title

      Optional<String> title()
      Fixed notification title; falls back to appName() when unset.

    • appName

      Optional<String> appName()
      Application name, used as the title base when title() is unset.

    • maxStackFrames

      @WithDefault("5") int maxStackFrames()
      Maximum root-cause stack frames rendered into an alert body.

    • connectTimeout

      @WithDefault("5s") String connectTimeout()
      HTTP connect timeout (ntfy duration spelling, e.g. 5s).

    • requestTimeout

      @WithDefault("10s") String requestTimeout()
      HTTP request timeout (ntfy duration spelling, e.g. 10s).

    • maxAlertsPerWindow

      @WithDefault("3") int maxAlertsPerWindow()
      Maximum individually-published alerts per suppression window before digesting kicks in.

    • suppressionWindow

      @WithDefault("3m") String suppressionWindow()
      Storm-suppression window (ntfy duration spelling, e.g. 3m).

    • errorPriority

      @WithDefault("high") String errorPriority()
      ntfy priority header for individual error alerts.

    • digestPriority

      @WithDefault("urgent") String digestPriority()
      ntfy priority header for the periodic storm digest.

    • errorTags

      @WithDefault("rotating_light") String errorTags()
      ntfy tags header for individual error alerts.

    • digestTags

      @WithDefault("fire") String digestTags()
      ntfy tags header for the periodic storm digest.

    • warnTopic

      Optional<String> warnTopic()
      The ntfy topic WARN-level events are published to. Unset by default, which keeps alerting ERROR-only; a non-blank value is the entire opt-in for WARN alerting. Set it to the same value as quarkus.ntfy.topic to alert on warnings through the main topic at a different priority.

    • warnPriority

      @WithDefault("default") String warnPriority()
      ntfy priority header for WARN alerts and the WARN digest.

    • warnTags

      @WithDefault("warning") String warnTags()
      ntfy tags header for WARN alerts and the WARN digest.

    • clickUrl

      Optional<String> clickUrl()
      URL opened when a notification is tapped (ntfy Click header). Omitted when unset.

    • actions

      Optional<String> actions()
      Action buttons as a raw ntfy Actions header value (short format, e.g. "view, View logs, https://grafana.example.com/d/abc"). Omitted when unset.

    • excludedLoggers

      Optional<String> excludedLoggers()
      Comma-separated logger-name prefixes excluded from alerting.

    • excludedExceptionTypes

      Optional<String> excludedExceptionTypes()
      Comma-separated fully qualified exception class names. An event whose cause chain contains any of them never alerts — matched anywhere in the chain, not just on the surface throwable.

    • cache

      @WithDefault("true") boolean cache()
      false asks the server not to store the message (Cache: no). Subscribers who are offline at that moment never receive it. Default true.

    • firebase

      @WithDefault("true") boolean firebase()
      false asks the server not to forward the message to Firebase ( Firebase: no). Default true.

    • icon

      Optional<String> icon()
      URL of the icon shown beside the notification (ntfy Icon header). Must be an http/https URL; a value that is not one is dropped — reported at startup on the alerting path, silently by the injectable NtfyClient, which has no diagnostics channel. ntfy renders JPEG and PNG only, but that is a property of the bytes served, not of the path, so a URL whose extension names another format is warned about and still sent.

    • iconsByLogger

      Optional<String> iconsByLogger()
      Per-logger icon overrides as prefix=url pairs separated by commas. The longest prefix matching an alert's logger wins; anything unmatched keeps the default icon. Alerts only — a notification has no logger to match on.

    • includeMdcKeys

      Optional<String> includeMdcKeys()
      Comma-separated allow-list of MDC keys whose values are rendered into alert bodies, one key: value line each, in the order given here.

      Empty by default: unless an operator names a key, no MDC value ever leaves the application. There is deliberately no wildcard form — an MDC routinely holds session tokens, user identifiers and other data that must not be pushed to a notification server, so the only way to publish a value is to name its key explicitly. Unknown keys and keys absent from a given record are simply skipped.

      Values are read from the JBoss LogManager MDC that Quarkus already funnels every log record through, so the usual org.jboss.logmanager.MDC / org.slf4j.MDC writes are picked up with no further wiring.

    • locale

      Optional<String> locale()
      Language of notification bodies and diagnostics as a BCP 47 tag (e.g. fr, de-DE). Defaults to English when unset; an unknown/unshipped locale silently uses English.

    • enabled

      @WithDefault("true") boolean enabled()
      Master switch; when false the handler is never installed.

    • async

      @WithDefault("true") boolean async()
      Asynchronous (offloaded) delivery: individual error alerts are handed to the engine's bounded work queue and published by a daemon worker, so a slow/unreachable ntfy server never blocks the logging thread. On by default; set false for pre-2.0 synchronous delivery.

    • asyncQueueCapacity

      @WithDefault("1024") int asyncQueueCapacity()
      Bounded async delivery queue capacity; only consulted when async() is true.

    • requireHttpsForCredentials

      @WithDefault("true") boolean requireHttpsForCredentials()
      Strict mode: refuse engine activation (rather than only warn) when credentials would be sent over a cleartext http:// endpoint. On by default; set false for the pre-2.0 warn-and-activate behavior.

    • startupPing

      @WithDefault("off") String startupPing()
      Opt-in startup self-test: off (default), probe (read-only reachability check that publishes nothing) or publish (a real low-priority test notification). Verifies at boot that the configured endpoint, credentials and topic actually work, instead of finding out when the first real error alert fails to deliver.

      Typed String rather than the StartupPingMode enum deliberately: SmallRye Config fails the whole application on an unconvertible enum value, so a single typo in application.properties would take the service down. The core parses it leniently and warns instead, which is also what the other five surfaces do.

    • startupPingFailFast

      @WithDefault("false") boolean startupPingFailFast()
      Whether a failed startup self-test aborts application startup instead of only warning. Off by default; enabling it also makes the self-test run inline, adding at most connect+request timeout to boot. Intended for CI/staging rather than production.

    • startupPingWarn

      @WithDefault("off") String startupPingWarn()
      Startup self-test for the optional WARN route: off (default), probe or publish. Independent of startupPing() — ntfy grants permissions per topic, so a healthy ERROR route proves nothing about the WARN one.

    • startupPingNotifyFailures

      @WithDefault("true") boolean startupPingNotifyFailures()
      Whether a failed self-test is announced as a notification on a route that PASSED. On by default; it can never fire unless some route passed, so it cannot publish to a topic the self-test has not just verified.