feat: make --aws-batch-job-role optional for pre-existing job definitions

[nh13]

A pre-existing job definition (--aws-batch-job-definition) carries its own role, so the plugin rejects --aws-batch-job-role in that mode. But job_role was required: True at the settings layer, forcing users to supply the very flag pre-existing mode rejects — so the setting-level pre-existing path was effectively unusable (it always tripped the "cannot combine" guard).

This makes job_role optional at the settings layer and enforces it conditionally in the startup preflight check:

• Reject --aws-batch-job-role combined with --aws-batch-job-definition (fail fast, before any queue/IAM call).
• Require --aws-batch-job-role in the default register-per-job mode, where it is baked into each registered definition — preserving the previous guarantee, now enforced in preflight rather than by required: True.

Docs and unit tests updated. Stacked on #49 (preflight validation); the first commit is #49's and will drop out once that merges.

Summary by CodeRabbit

• New Features

  • Added AWS Batch startup validation to detect invalid queues, compute environments, and missing IAM roles before jobs are submitted.
  • Added conditional validation for job definitions and job roles, with clear errors for incompatible or incomplete settings.
  • Transient AWS errors and unavailable permissions produce warnings while allowing execution to continue.

• Documentation

  • Documented preflight checks, required permissions, and job definition/job role configuration rules.

[coderabbitai]

Warning

Review limit reached

@nh13, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 50 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 22ff1edf-b43c-4271-b297-5e93fbbedc94

📥 Commits

Reviewing files that changed from the base of the PR and between 65a84ea and 938a7d1.

📒 Files selected for processing (4)

• docs/further.md
• snakemake_executor_plugin_aws_batch/__init__.py
• tests/test_preflight.py
• tests/tests_mocked_api.py

📝 Walkthrough

Walkthrough

The executor now performs AWS Batch and optional IAM role preflight validation during startup, failing on confirmed misconfiguration while continuing through uncertain API or permission states. Documentation and tests cover these checks and mocked workflows bypass them.

Changes

AWS Batch preflight validation

Layer / File(s)	Summary
Preflight orchestration and configuration checks snakemake_executor_plugin_aws_batch/__init__.py, docs/further.md	Startup validation invokes Batch checks, applies conditional job-role rules, and documents pre-existing job-definition behavior.
Batch and IAM resource checks snakemake_executor_plugin_aws_batch/__init__.py, docs/further.md	Queue, compute-environment, and IAM role checks distinguish confirmed failures from transient, permission, or otherwise uncertain conditions.
Preflight behavior coverage tests/test_preflight.py, tests/tests_mocked_api.py	Tests cover invalid resources, recoverable states, role errors, conditional configuration, and mocked workflows that bypass AWS-backed preflight calls.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Executor
  participant AWS Batch
  participant IAM
  Executor->>AWS Batch: Describe job queue and compute environments
  AWS Batch-->>Executor: Return resource states
  Executor->>IAM: Get configured role
  IAM-->>Executor: Return role or error
  Executor-->>Executor: Fail on confirmed misconfiguration or continue

Loading

Possibly related PRs

• snakemake/snakemake-executor-plugin-aws-batch#7: Modifies the job_role configuration used by this validation.
• snakemake/snakemake-executor-plugin-aws-batch#13: Adjusts mocked AWS Batch executor behavior in related workflow tests.
• snakemake/snakemake-executor-plugin-aws-batch#40: Adds Batch client introspection used by queue and compute-environment validation.

Suggested reviewers: cademirch

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: making --aws-batch-job-role optional when using a pre-existing job definition.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@snakemake_executor_plugin_aws_batch/__init__.py`:
- Around line 457-467: Update the compute-environment validation loop in the
preflight logic to aggregate usability across all queue-attached compute
environments rather than adding a fatal problem for each individual disabled,
invalid, or zero-capacity environment. Only report failure when every attached
compute environment is unusable, while allowing execution when at least one is
healthy; add a regression test covering a queue with mixed healthy and unhealthy
compute environments.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 01a10571-f671-49fb-9193-a8ed11f5b5ef

📥 Commits

Reviewing files that changed from the base of the PR and between bc0a9af and 65a84ea.

📒 Files selected for processing (4)

• docs/further.md
• snakemake_executor_plugin_aws_batch/__init__.py
• tests/test_preflight.py
• tests/tests_mocked_api.py

🚧 Files skipped from review as they are similar to previous changes (3)

• tests/tests_mocked_api.py
• docs/further.md
• tests/test_preflight.py