Firefly v1.0.3

Release date: August 2, 2026

v1.0.3 focuses on runtime ownership and input boundaries. It does not add a large web framework or ORM, nor does it change Netty's transport role. Instead, implicit rules around cancellation, timeout, critical writes, shutdown, and protocol messages now have narrower, testable entry points and explicit failure behavior.

Artifact publication status

The v1.0.3 source tag and Maven Central artifacts are published. Historical artifacts remain available in Central Portal; new projects should use the current 1.0.6 release.

Migration scope

This release deliberately does not address recovery from a failed MySQL initialization migration. Fresh database initialization follows the existing flow; production upgrades should continue to use the DBA migration window and backup policy.

Highlights

Execution and Outbox lifecycle

• ExecutionLifecycleService and JdbcExecutionLifecycleStore provide one lifecycle entry point for cancellation and timeout handling.
• JDBC cancellation and timeout paths update execution, targets, and dispatch outbox within their respective transactions. Admin cancellation no longer invokes Execution and Job repositories in sequence.
• JobCatalog, SchedulingStore, DispatchOutboxStore, and ExecutionRetryStore make store capabilities explicit, and JdbcJobRepository declares the full set it implements.
• The JobRepository facade remains for compatibility. Most unsupported Outbox operations now throw UnsupportedOperationException, but migration to the narrower interfaces is not complete.

Admin requests and server options

• Batch cancellation, batch requeue, and job enable/disable use Jackson request records. Array elements no longer depend on comma splitting, so IDs containing commas remain intact.
• Admin writes and server boolean options accept only true or false; values such as treu fail the request or startup.
• OptionSpec and OptionSchema establish typed option infrastructure, initially enforcing names in the core JWT namespace. Plugin configuration and JWT client extensions remain open.
• Other compatibility Admin routes can still use the existing Map reader; this release does not convert every request to a record.

Worker shutdown and Netty protocol

• ManagedWorker standardizes the sequence of shutdownNow(), an await of up to five seconds, timeout logging, and an ownership-release callback.
• The node coordinator blocks new reconcile entry after shutdown begins. Lease release and offline marking run after the await phase, including when the await times out.
• Netty adds RegisterExecutorFrame, AckJobFrame, ReportResultFrame, and NettyExecutorFrameMapper; Gateway validates required fields before entering the corresponding business branch.
• The compatible NettyExecutorMessage envelope and the existing Gateway Handler remain. Command-handler extraction and protocol upcasters are outside this release.

Outbox snapshots

• New snapshots add a JSON envelope with schemaVersion: 1 around the existing Map payload, while historical v0 Map values remain readable.
• Missing or invalid booleans such as enabled, retryOnFailure, and retryOnTimeout fail explicitly instead of silently becoming false.
• This release versions the outer envelope. Its payload remains a Base64-encoded legacy Map rather than a complete JSON JobDefinition schema.

Upgrade checklist

1. Existing projects can upgrade to 1.0.3; new projects should use the current 1.0.6 release.
2. In staging, verify Admin batch cancellation, batch requeue, comma-containing IDs, and malformed booleans return 4xx responses.
3. Inspect node shutdown logs. Normally leases are released after the worker await phase; investigate any five-second timeout warning as an unresponsive task.
4. Ensure custom Netty clients still provide protocol version, instance, and session fields and satisfy required Register, ACK, and Result frame fields.
5. MySQL initialization migration recovery is outside this release; use the existing DBA procedure and retain a rollback backup.

Non-goals and known boundaries

• Exactly-once execution is not promised; business side effects still need unique keys or transactional idempotency.
• The compatible JobRepository facade, generic Admin Map reader, and centralized Netty Gateway Handler remain. This release establishes boundaries for incremental migration.
• ManagedWorker provides a bounded wait rather than an indefinite block. The release callback still runs after a timeout, so timeout warnings are operational signals rather than successful completion.
• Schema initialization behavior is unchanged; MySQL mid-migration recovery requires separate design and verification.

See the complete source at the Firefly v1.0.3 tag.