Cloud connection lifecycle

Querying connection state, forcing reconnects, and the event family that models the lifecycle.

Reading and steering the connection

The dependable, version-stable surface is CloudService — query it any time, from any thread:

Signature	Description
`boolean connected()`	Ground truth for whether the websocket is up.
`void reconnect()`	Forces a reconnect attempt; no-op when already connected.
`String serverName()`	The name this server registered with the cloud.
`void forget(User)`	Drops cloud-held state for one player.

Lifecycle events

The API declares an event family for the connection transitions, all extending CloudConnectionEvent:

xyz.kaosmc.anticheat.api.server.event

public abstract class CloudConnectionEvent extends VenusApiEvent {
    public @NotNull String host();
    public int port();
}

public final class CloudConnectedEvent  extends CloudConnectionEvent { }
public final class CloudReconnectEvent  extends CloudConnectionEvent {
    public int attempt();              // which retry this is
}
public final class CloudDisconnectedEvent extends CloudConnectionEvent {
    public int statusCode();
    public @Nullable String reason();
}

listening for lifecycle transitions

api.events().repository().register(CloudDisconnectedEvent.class, event ->
        getLogger().warn("Cloud lost: " + event.statusCode() + " " + event.reason()));

api.events().repository().register(CloudReconnectEvent.class, event ->
        getLogger().info("Cloud reconnect attempt " + event.attempt()));

Server-scope siblings

Two non-cloud events share the api.server.event package because they describe the installation rather than a player:

Signature	Description
`ReloadEvent#successful()`	Fired after a configuration reload completes; success() and failure() factory helpers exist. Distinguishes API-initiated and console reloads by the same payload.
`CloudConnectionEvent subclasses above`	Host, port and transition-specific fields.

Failure behaviour

A dropped connection never stops local checks — the cloud is additive, and every local alert, history and punishment path works with it offline.
Reconnects retry with the attempt counter exposed on CloudReconnectEvent; telemetry produced while offline is not replayed, windows simply resume.
Mitigations already applied do not expire while the cloud is unreachable — they lapse on the normal timer once the connection resumes.

Setup context in the cloud overview; per-user mitigation state in detections and mitigations.