Introduce `FailableProvider` for better error handling in GradleExec #435

FinlayRJW · 2025-08-19T08:58:49Z

Before this PR

GradleExec.exec() returned a raw Provider<ExecResultWithOutput> that required manual exit code checking and error handling, leading to boilerplate code and inconsistent error messages.

After this PR

GradleExec.exec() returns a FailableProvider<ExecResultWithOutput> that:

Throws descriptive ExecFailedException on non-zero exit codes by default
Supports custom error handling via .mapFailure() and .handle()
Provides graceful fallbacks with .getOrElse() and .getOrNull()
Propagates failures through standard provider operations (map, flatMap, zip)

==COMMIT_MSG==
Introduce FailableProvider for better error handling in GradleExec

GradleExec.exec() now returns a FailableProvider that automatically throws
descriptive exceptions on non-zero exit codes while supporting custom error
handling through mapFailure() and fold() methods.
==COMMIT_MSG==

Possible downsides?

Breaking change: Return type changed from Provider<ExecResultWithOutput> to FailableProvider<ExecResultWithOutput>. While FailableProvider extends Provider, .get() now throws on non-zero exit codes instead of returning silently. Use .getRaw() for old behavior.

changelog-app · 2025-08-19T08:58:54Z

Generate changelog in `changelog/@unreleased`

Type (Select exactly one)

Feature (Adding new functionality)
Improvement (Improving existing functionality)
Fix (Fixing an issue with existing functionality)
Break (Creating a new major version by breaking public APIs)
Deprecation (Removing functionality in a non-breaking way)
Migration (Automatically moving data/functionality to a new system)

Description

Introduce FailableProvider for better error handling in GradleExec

GradleExec.exec() now returns a FailableProvider that automatically throws
descriptive exceptions on non-zero exit codes while supporting custom error
handling through mapFailure() and handle() methods.

Check the box to generate changelog(s)

Generate changelog entry

changelog-app · 2025-08-20T16:46:00Z

✅ Successfully generated changelog entry!

What happened?

Your changelog entries have been stored in the database as part of our migration to ChangelogV3.

Need to regenerate?

Simply interact with the changelog bot comment again to regenerate these entries.

🔄 Changelog entries were re-generated at Fri, 29 Aug 2025 09:03:09 UTC!

Copilot

Pull Request Overview

This PR introduces FailableProvider<T> to improve error handling in GradleExec by automatically throwing descriptive exceptions on non-zero exit codes while providing flexible error handling options.

Key changes:

Introduces FailableProvider interface and DefaultFailableProvider implementation for failure-aware providers
Changes GradleExec.exec() return type from Provider<ExecResultWithOutput> to FailableProvider<ExecResultWithOutput>
Updates existing usage in GradleOperatingSystem to use the new error handling capabilities

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`providers/src/main/java/com/palantir/gradle/utils/providers/FailableProvider.java`	Defines the interface for failure-aware providers with methods like `mapFailure()` and `fold()`
`providers/src/main/java/com/palantir/gradle/utils/providers/DefaultFailableProvider.java`	Implements the FailableProvider interface with failure detection and custom error handling
`exec/src/main/java/com/palantir/gradle/utils/exec/GradleExec.java`	Updates exec() method to return FailableProvider with automatic failure detection
`exec/src/main/java/com/palantir/gradle/utils/exec/ExecResultWithOutput.java`	Extracts ExecResultWithOutput interface into separate file
`exec/src/main/java/com/palantir/gradle/utils/exec/ExecFailedException.java`	Adds specialized exception for process execution failures
`platform/src/main/java/com/palantir/platform/GradleOperatingSystem.java`	Updates to use fold() method for handling both success and failure cases

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

providers/src/main/java/com/palantir/gradle/utils/providers/DefaultFailableProvider.java

kelvinou01

Very cool idea and clean implementation! Here are some initial thoughts before lunchtime, but I'm still simmering on this.

kelvinou01 · 2025-08-29T10:40:12Z

exec/src/main/java/com/palantir/gradle/utils/exec/ExecFailedException.java

+/**
+ * Exception thrown when a process execution fails with a non-zero exit code.
+ */
+public class ExecFailedException extends RuntimeException {


Should we make ExecFailedException a checked exception, so that we force people to wrap it in SafeRuntimeException or UnsafeRuntimeException with their own context?

Not sure if the context added is worth the extra code it requires. But since this is a library, it might be a good idea?

I'm torn on this, I think FallibleProvider must use RuntimeException because it extends Gradle's Provider<T> interface, which doesn't declare checked exceptions on get(), so we would need to wrap ourselves in GradleExec. but it would be nice to force / encourage users to provider there own context

exec/src/test/java/com/palantir/gradle/utils/exec/GradleExecTest.java

kelvinou01 · 2025-08-29T10:46:06Z

exec/src/main/java/com/palantir/gradle/utils/exec/GradleExec.java

+     * Executes a process and returns a FailableProvider for the result.
     * <p>
-     * This method always sets {@code ignoreExitValue} to {@code true} on the {@code ExecSpec},
-     * ensuring that the build does not fail regardless of the process exit code. Callers do need
-     * to handle exit codes manually.
-     * <p>
-     * The result includes the process's standard output, standard error, and the {@link ExecResult}.
+     * Usage:
+     * <pre>
+     * def result = gradleExec.exec {
+     *     commandLine 'git', 'status'
+     * }
+     *
+     * // Handle success/failure
+     * result.handle(
+     *     { output -> println "Success: ${output.stdOut}" },
+     *     { output -> println "Failed: ${output.stdErr}" }
+     * )
     *
-     * @param action an action to configure the {@link ExecSpec} for the process to be executed
-     * @return a Provider of {@link ExecResultWithOutput} containing the standard output, standard error,
-     *         and execution result
+     * // Or throw on failure
+     * def output = result.get().stdOut
+     * </pre>
     */


We should explicate the tribal knowledge that GradleExec is needed, and people should use GradleExec, because ProviderFactory::exec doesn't give good stack traces.

Maybe even errorprone away usages of ProviderFactory::exec to GradleExec

yeah think an errorprone is great idea - I've updated the javadoc to be more explicit as well

added an errorprone see - palantir/gradle-guide#210

exec/src/main/java/com/palantir/gradle/utils/exec/ExecResultWithOutput.java

providers/src/main/java/com/palantir/gradle/utils/providers/FailableProvider.java

exec/src/main/java/com/palantir/gradle/utils/exec/GradleExec.java

FinlayRJW added 2 commits August 19, 2025 09:51

better error handling

e5b6abd

new lines

4a95d0b

FinlayRJW added 4 commits August 19, 2025 10:44

slightly better

e10c60d

slightly better

e40f94b

nice finally

538a032

dont truncate

15df701

FinlayRJW changed the title ~~Finlayw/better error~~ Introduce FailableProvider for better error handling in GradleExec Aug 20, 2025

tidy up

0a35fcb

FinlayRJW mentioned this pull request Aug 21, 2025

Add configuration cache allow list validation task palantir/gradle-incremental-configuration-cache#63

Closed

FinlayRJW requested a review from Copilot August 21, 2025 15:26

Copilot AI reviewed Aug 21, 2025

View reviewed changes

FinlayRJW added 3 commits August 29, 2025 09:21

tidy

a350985

tidy up

2252b25

resolve merge conflict

7593e0b

FinlayRJW marked this pull request as ready for review August 29, 2025 09:06

kelvinou01 reviewed Aug 29, 2025

View reviewed changes

FinlayRJW added 7 commits September 1, 2025 11:28

rename

9454a0c

rename

aed9050

failOn

f9d72fc

improve javadoc

0c0b1ea

move to gradle exec result

1f72001

update readme

fccb3b6

update readme

db1027e

FinlayRJW mentioned this pull request Sep 1, 2025

use GradleExec#exec over ProviderFactory#exec palantir/gradle-guide#210

Open

FinlayRJW changed the title ~~Introduce FailableProvider for better error handling in GradleExec~~ Introduce FailableProvider for better error handling in GradleExec Sep 1, 2025

FinlayRJW added 3 commits October 3, 2025 13:23

merge

5c02423

suppress

ee35358

suppress

bf2d9c9

Introduce FailableProvider for better error handling in GradleExec #435

Are you sure you want to change the base?

Introduce FailableProvider for better error handling in GradleExec #435

Uh oh!

Conversation

FinlayRJW commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Before this PR

After this PR

Possible downsides?

Uh oh!

changelog-app bot commented Aug 19, 2025 • edited by FinlayRJW Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Generate changelog in changelog/@unreleased

Uh oh!

changelog-app bot commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Successfully generated changelog entry!

What happened?

Need to regenerate?

🔄 Changelog entries were re-generated at Fri, 29 Aug 2025 09:03:09 UTC!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kelvinou01 left a comment

Choose a reason for hiding this comment

Uh oh!

kelvinou01 Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

FinlayRJW Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kelvinou01 Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kelvinou01 Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FinlayRJW Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

FinlayRJW Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Introduce `FailableProvider` for better error handling in GradleExec #435

Introduce `FailableProvider` for better error handling in GradleExec #435

FinlayRJW commented Aug 19, 2025 •

edited

Loading

changelog-app bot commented Aug 19, 2025 •

edited by FinlayRJW

Loading

Generate changelog in `changelog/@unreleased`

changelog-app bot commented Aug 20, 2025 •

edited

Loading

kelvinou01 Aug 29, 2025 •

edited

Loading

kelvinou01 Aug 29, 2025 •

edited

Loading