feat: add failOnError option to abort pipeline on notification failures

[adamrtalbot]

Implements the failOnError configuration option requested in #45.

When failOnError = true, any Slack notification failure will throw a RuntimeException and abort the pipeline. When false (default), errors are logged as warnings and the pipeline continues.

Closes #45

Generated with Claude Code

[claude]

Review: feat: add failOnError option

The implementation is clean — the handleNotificationError helper centralizes the logic well, and the exception-propagation refactor in the senders is solid.

Issues

Documentation missing
failOnError is not documented in docs/reference/api.md (the config reference table) or docs/usage/guide.md. Every other config option like validateOnStartup is listed there — this one should be too.

No example config
example/configs/ has configs for each notable feature but none for failOnError. Even a one-liner in an existing config (e.g. 01-minimal.config) would help users discover it.

Missing tests in SlackExtensionTest
The slackMessage(), slackMessage(Map), and slackFileUpload() functions in SlackExtension all have the failOnError branch, but SlackExtensionTest.groovy has zero coverage of that path. The observer tests cover the flag well — the extension needs the same.

Silent behavior change at default settings
With failOnError = false (the default), reaction failures previously logged at DEBUG. They now log at WARN (via handleNotificationError). This affects existing users who haven't opted in to failOnError and should be called out in the changelog/docs.

[claude]

Code Review

This PR adds a failOnError config option that converts all Slack notification failures from silent log-and-continue into pipeline-aborting RuntimeExceptions. The refactor is clean overall: senders now throw, handleNotificationError centralizes the log/throw decision in the observer, and tests are updated to match. A few issues need attention before merging.

---

Findings (most severe first)

WebhookSlackSender.groovy:101 — failOnError=true is silently ignored for webhook file uploads

WebhookSlackSender.uploadFile only logs a warning and returns without throwing:

void uploadFile(Path filePath, Map options) {
    log.warn "Slack plugin: File upload is not supported with webhooks..."
}

Because it never throws, uploadConfiguredFiles in the observer completes without entering the catch block, so handleNotificationError is never called and the pipeline never aborts — even when failOnError = true. The docs promise this setting aborts on "messages, file uploads, reactions, or extension calls", but this case is silently violated. Fix: throw an UnsupportedOperationException from WebhookSlackSender.uploadFile so the observer's catch path picks it up normally.

---

SlackExtension.groovy:88,146,232 — log.error before conditional rethrow is inconsistent with handleNotificationError

All three extension catch blocks unconditionally log at log.error before conditionally rethrowing:

} catch (Exception e) {
    def msg = "Slack plugin: Error sending message: ${e.message}"
    log.error msg, e          // always ERROR, even when failOnError=false
    if (observer.config?.failOnError) {
        throw new RuntimeException(msg, e)
    }
}

handleNotificationError intentionally uses log.warn before throwing (reserving log.error for the framework's own exception reporting). The extension does the opposite: logs ERROR first, then throws — likely producing two ERROR-level entries per failure when failOnError=true. When failOnError=false it logs a recoverable failure at ERROR instead of WARN. Change to log.warn to match handleNotificationError.

---

BotSlackSender.groovy:124,132 — Dead null/false checks after methods that now always throw

getUploadUrl returns a non-null Map or throws — never null. uploadFileContent returns true or throws — never false. Both guards are unreachable:

def uploadInfo = getUploadUrl(filename, fileSize)
if (!uploadInfo) {           // dead: getUploadUrl never returns null
    throw new RuntimeException(...)
}
...
if (!uploadFileContent(uploadUrl, filePath)) {   // dead: always returns true or throws
    throw new RuntimeException(...)
}

Remove both dead branches.

---

WebhookSlackSender.groovy:24-27 — Stale class docstring

The class doc still reads:

 * - Graceful error handling (never fails workflow)

but sendMessage now throws RuntimeException on non-200 responses. Update the docstring to match the new contract.

[adamrtalbot]

Addressed Claude review in ac9a548:

• Documented failOnError in docs/reference/api.md and docs/usage/guide.md.
• Added commented example in example/configs/01-minimal.config.
• Added SlackExtensionTest coverage for failOnError true/false paths.
• Reaction failures log at DEBUG when failOnError=false (preserves prior behavior); other failures still WARN.
• Updated CHANGELOG.md and aligned sender tests with throw-on-failure semantics.

./gradlew test passes locally (151 tests).