Firefly v1.0.5

Merge date: August 7, 2026

v1.0.5 adds firefly-remote-adapter for traditional Java, Servlet, Guice, and command-line workers. Business services can use Firefly Gateway connections, heartbeats, reconnection, idempotent result storage, and graceful shutdown without introducing Spring.

The existing Spring Boot Starter path remains intact. Remote Adapter is an additional framework-neutral entry point; it does not replace the Starter or move scheduling-definition ownership into the business process.

Artifact publication status

The v1.0.5 implementation was merged into master through Firefly PR #26, but no v1.0.5 source tag or GitHub Release exists yet. Before adoption, confirm in Central Portal that version 1.0.5 of firefly-bom, firefly-remote-adapter, and the Starter has been published and indexed.

Non-Spring Java Remote Adapter

New Maven Central artifact:

io.github.fishered:firefly-remote-adapter:1.0.5

The Adapter owns the business-side Executor connection and lifecycle:

• Loads firefly.executor.* properties and matching FIREFLY_EXECUTOR_* environment variables.
• Connects to one or more Gateways with Integration Key authentication, heartbeats, and reconnection.
• Reports successful startup only after Gateway returns REGISTERED.
• Advertises the running instance's Handler capabilities and receives real task dispatches.
• Reuses Netty Executor idempotent result storage, TLS, and graceful shutdown behavior.

Stable Handler entrypoints

Fixed business methods use the framework-neutral @FireflyHandler annotation without Spring:

import com.firefly.domain.ExecutionContext;
import com.firefly.integration.remote.FireflyHandler;
import com.firefly.integration.remote.RemoteExecutorAdapter;
import com.firefly.integration.remote.RemoteHandlerProvider;

final class BillingHandlers {
    @FireflyHandler
    void billing(ExecutionContext context) {
        // run business code
    }
}

RemoteExecutorAdapter.run(
        RemoteHandlerProvider.annotated(new BillingHandlers())
);

The Adapter derives package.Class#method, for example:

com.example.BillingHandlers#billing

• The annotation has no manually maintained Handler name, avoiding duplicate names and configuration drift.
• Only explicitly supplied business objects are inspected; there is no global classpath scan.
• Methods must return void and accept either no arguments or one ExecutionContext.
• Annotated overloads in one class produce the same entrypoint and fail before Gateway connection.
• Low-level string-based .bind(name, handler) remains available for dynamic or legacy integrations.

Executor and scheduling ownership

Remote Adapter uses an existing-only Executor registration policy:

1. Create a fixed TCP Executor in Admin first.
2. Start the business service with the same firefly.executor.name.
3. The Adapter registers only the running instance and its Handler capabilities.
4. Jobs, Cron, routing, retries, and enablement remain managed through Admin UI/API.

Gateway rejects an unknown Executor even when legacy client auto-creation remains enabled globally. Existing Netty clients retain their compatible default behavior.

Minimal environment configuration:

FIREFLY_EXECUTOR_NAME=billing-executor
FIREFLY_EXECUTOR_GATEWAY_ADDRESSES=firefly-1:9700,firefly-2:9700
FIREFLY_EXECUTOR_INTEGRATION_KEY=replace-with-integration-key

Firefly BOM

io.github.fishered:firefly-bom:1.0.5 pins the Firefly version once for a Maven project:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.fishered</groupId>
            <artifactId>firefly-bom</artifactId>
            <version>1.0.5</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Choose one dependency for the service type without repeating the version. Spring Boot services use:

<dependency>
    <groupId>io.github.fishered</groupId>
    <artifactId>firefly-spring-boot-starter</artifactId>
</dependency>

Non-Spring Java services use:

<dependency>
    <groupId>io.github.fishered</groupId>
    <artifactId>firefly-remote-adapter</artifactId>
</dependency>

The BOM aligns scheduler-core, plugin-api, netty-protocol, netty, executor-netty, Remote Adapter, Spring Boot Autoconfigure, and Starter. It does not dynamically select the latest network release.

Spring Boot compatibility

• The existing firefly-spring-boot-starter integration and auto-configuration behavior remain unchanged.
• @FireflyJob, job synchronization, Gateway registration, health reporting, and Spring lifecycle behavior continue as before.
• Isolated Maven consumers pass with Spring Boot 3.3.5, 3.4.12, 3.5.8, and 4.0.0.
• No database schema migration is required.

Explicitly deferred scope

v1.0.5 delivers only the non-Spring Java Adapter. Python, Go, generic HTTP Handlers, and the language-neutral Agent are outside this release. A future Agent will provide one protocol boundary, while language SDKs will remain thin wrappers around configuration, protocol, and local Handler invocation.

Verification

• Fixed Executor registration, real dispatch, reconnection, and shutdown coverage passes for Remote Adapter.
• Unknown Executors, empty or duplicate Handler sets, and invalid annotated signatures fail at the expected stage.
• TLS property names align with the Spring Starter.
• Generated-POM checks cover BOM coordinates, pom packaging, and every managed module version.
• The complete unit suite, real-database suite, and four Spring Boot compatibility jobs pass in CI.

See Quick Start and Integration for the complete setup.