Event Types and Lifecycle

Federation synchronization is driven by events. Every operation on a Federated repository, including deploying an artifact, updating properties, deleting a file, or modifying repository configuration, generates an event that propagates to other Federation members.

Artifact Event Types

When an artifact operation occurs on a Federated repository, an event of one of the following types is generated.

Repository Event Types

Repository-level operations generate a separate class of events.

Event Lifecycle

flowchart LR
    subgraph source ["Source Member"]
        op["Artifact operation"] --> ev["Event generated"]
        ev --> queue["Event queue (persistent)"]
    end

    subgraph rtfs ["RTFS"]
        worker["Worker picks up event batch"]
        worker --> dedup["Deduplication"]
        dedup --> propagate["Propagate to target members"]
    end

    subgraph target ["Target Member"]
        receive["Receive event"]
        receive --> apply["Apply metadata"]
        apply --> binary{"Binary needed?"}
        binary -->|Yes| task["Create binary task"]
        binary -->|No| done["Complete"]
        task --> transfer["Transfer binary"]
        transfer --> done
    end

    queue --> worker
    propagate --> receive

    classDef component fill:#41b375,stroke:#389b65,stroke-width:1px,color:#fff;
    classDef secondary fill:#ffffff,stroke:#41b375,stroke-width:1.5px,color:#41b375;
    class op,ev,queue,worker,dedup,propagate,receive,apply,task,transfer component;
    class binary,done secondary;

    style source fill:none,stroke:#41b375,stroke-width:1px;
    style rtfs fill:none,stroke:#41b375,stroke-width:1px;
    style target fill:none,stroke:#41b375,stroke-width:1px;

    linkStyle default stroke:#8e9aaf,stroke-width:1.5px;

Step-by-Step Flow

1. Event generation: An artifact or repository operation on a member generates an event with the operation type, artifact path, metadata, and checksums.
2. Persistent queueing: The event is written to a persistent database-backed queue, ensuring durability across restarts.
3. Worker processing: RTFS workers poll the queue in configurable batches (rtfs.worker.batch.size, default: 100 events). HIGH and URGENT priority repositories use larger batches (up to 400 events).
4. Deduplication: Before propagation, the system deduplicates events. For example, if the same artifact is created and then deleted before the CREATE event was propagated, the deduplication logic can eliminate both events (controlled by federated.skip.create.eliminate.delete.on.deduplication).
5. Propagation: Events are sent to each target member based on mirror mode. Bidirectional members send and receive. Receiving-only members only receive. Transmitter members only send.
6. Binary task creation: If a CREATE or UPDATE event references a binary that doesn't exist on the target member, a binary task is created to transfer the file content.
7. Completion: The event is marked as processed. Failed events are retried up to the configured limit (federated.event.queue.max.error.retries, default: 6).

Event Retention and Cleanup

Processed events are retained for a configurable period and then cleaned up. If a prolonged outage delays propagation past the retention window, the cleanup job can purge unpropagated events, forcing an affected member into an out-of-sync state that requires a Full Sync to recover.

Event Deduplication

The deduplication system reduces redundant event propagation.

Grace Period

To avoid race conditions between nearly simultaneous events, a grace period controls the minimum interval between processing subsequent events for the same artifact.

Frequently Asked Questions

This section provides answers to frequently asked questions about Federation events and their lifecycle.

Related Topics

• Synchronization and Conflict Resolution
• Member States and Health
• Monitoring Binaries Tasks
• System Properties Reference