Package com.ultikits.ultitools.websocket

Class CloudPlayerLinks

java.lang.Object

com.ultikits.ultitools.websocket.CloudPlayerLinks

public final class CloudPlayerLinks
extends Object

Creates and tracks UltiCloud player links on a module's behalf; the framework's player-link API.

A player link proves that the person using the web panel is the owner of a game identity. A module creates one for a player (in practice when the player runs /panel); the gateway answers with a one-time URL the player opens in a browser; the gateway then reports how that web user proved the identity. A module never sees the server credential and never talks to UltiCloud over HTTP.

Link lifetime. A link lives playerLinkTtlSeconds = 600 seconds from issue, so CloudPlayerLinks.LinkCreation.expiresAt() is the issue time plus 600 seconds, and it is single use. Running /panel again for the same player cancels the previous link, which is reported as an CloudPlayerLinks.ExpiryReason.CANCELLED expiry. A link is not extended by using it.

Expiry reasons. CloudPlayerLinks.ExpiryReason.EXPIRED means nobody completed the link before it lapsed; CloudPlayerLinks.ExpiryReason.CANCELLED means it was replaced by a newer link or cancelled by the plugin or the player; CloudPlayerLinks.ExpiryReason.DENIED means the web user explicitly refused the confirmation page. The framework never synthesizes an expiry event: a link whose CloudPlayerLinks.LinkCreation.expiresAt() has passed without any event is the module's to treat as expired.

Creation failures. CloudPlayerLinks.Failure.LINK_NOT_PERMITTED means the gateway refused to issue a link because the server is suspended, the owner disabled player links, or the game identity is banned. CloudPlayerLinks.Failure.RATE_LIMITED means the gateway's rate limit was hit and the module may offer a retry. CloudPlayerLinks.Failure.TIMED_OUT and CloudPlayerLinks.Failure.NOT_CONNECTED mean the request never produced an answer.

Threading. Every call is non-blocking, including create(com.ultikits.ultitools.abstracts.UltiToolsPlugin, java.util.UUID, java.lang.String, com.ultikits.ultitools.websocket.CloudPlayerLinks.GameAuth, java.util.Set<com.ultikits.ultitools.websocket.CloudPlayerLinks.LinkProof>) from the server's primary thread. The registered CloudPlayerLinks.LinkEventHandler is always called on a framework worker thread, never on the socket thread or the primary thread; it may do blocking work and must complete its future from wherever the module's own work finishes. A handler that does not answer within 30 seconds, or that fails, produces no result, so the gateway redelivers the same completion later (the module is asked again).

Ownership. Exactly one module owns the handler at a time. It should set the handler when it is enabled and remove it on unload; while another module owns it, setHandler(com.ultikits.ultitools.abstracts.UltiToolsPlugin, com.ultikits.ultitools.websocket.CloudPlayerLinks.LinkEventHandler) throws IllegalStateException rather than taking events away from its owner.

Since:

6.3.1

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	CloudPlayerLinks.ExpiryReason	Why a link stopped being usable.
static enum	CloudPlayerLinks.Failure	Why a link request failed.
static enum	CloudPlayerLinks.GameAccountResult	What the handler reports about provisioning a game account for the linked player.
static final class	CloudPlayerLinks.GameAuth	What this server knows about the player's game authentication when the link is created.
static final class	CloudPlayerLinks.LinkCompletion	One completed link: how the web user proved the game identity, and what to provision.
static final class	CloudPlayerLinks.LinkCreation	The answer to one create(com.ultikits.ultitools.abstracts.UltiToolsPlugin, java.util.UUID, java.lang.String, com.ultikits.ultitools.websocket.CloudPlayerLinks.GameAuth, java.util.Set<com.ultikits.ultitools.websocket.CloudPlayerLinks.LinkProof>) call: either a link, or a failure with a safe message.
static interface	CloudPlayerLinks.LinkEventHandler	Receives completions and expiries of this server's links.
static final class	CloudPlayerLinks.LinkExpiry	One link that stopped being usable.
static enum	CloudPlayerLinks.LinkProof	An identity proof the server side can support for one link; the gateway decides which of the offered ones it actually accepts.
static interface	CloudPlayerLinks.Transport	The framework's transport for link messages; internal, not for module use.

Field Summary

Fields

Modifier and Type	Field	Description
private final CloudPlayerLinks.Transport	transport

Constructor Summary

Constructors

Constructor	Description
CloudPlayerLinks(CloudPlayerLinks.Transport transport)	Creates the API over a transport.

Method Summary

Modifier and Type	Method	Description
CompletableFuture<CloudPlayerLinks.LinkCreation>	create(UltiToolsPlugin requester, UUID playerUuid, String playerName, CloudPlayerLinks.GameAuth gameAuth, Set<CloudPlayerLinks.LinkProof> offeredProofs)	Asks the gateway for a one-time link for one player, without blocking.
void	removeHandler(UltiToolsPlugin owner)	Removes the handler when owner is the module that set it; other owners are ignored.
void	setHandler(UltiToolsPlugin owner, CloudPlayerLinks.LinkEventHandler handler)	Registers the handler for completions and expiries of this server's links.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

transport

private final CloudPlayerLinks.Transport transport

Constructor Details

CloudPlayerLinks

public CloudPlayerLinks(CloudPlayerLinks.Transport transport)

Creates the API over a transport.

Parameters:

transport - the transport that frames and tracks the protocol messages; never null

Method Details

create

public CompletableFuture<CloudPlayerLinks.LinkCreation> create(UltiToolsPlugin requester,
 UUID playerUuid,
 String playerName,
 CloudPlayerLinks.GameAuth gameAuth,
 Set<CloudPlayerLinks.LinkProof> offeredProofs)

Asks the gateway for a one-time link for one player, without blocking.

The returned future completes normally with a CloudPlayerLinks.LinkCreation that carries the URL or with a failure; it never completes exceptionally for a protocol-level outcome. The framework fills serverOnlineMode itself. For one link, the creation result is delivered before any completion or expiry of that link.

Parameters:

requester - the calling module, used for ownership and diagnostics

playerUuid - the player's Minecraft UUID

playerName - the player's Minecraft name as the module knows it

gameAuth - what this server knows about the player's game authentication

offeredProofs - the identity proofs this server can support, one to three of them

Returns:

a future that completes with the answer, never null

Throws:

NullPointerException - if requester, playerUuid or gameAuth is null, or if offeredProofs holds a null proof

IllegalArgumentException - if the name is null or empty, or the offered proofs are null, empty or hold more than three entries

Since:

6.3.1

setHandler

public void setHandler(UltiToolsPlugin owner,
 CloudPlayerLinks.LinkEventHandler handler)

Registers the handler for completions and expiries of this server's links.

One owner at a time: the same owner may replace its own handler, another owner while one is set is refused. The handler is called off the primary thread.

Parameters:

owner - the module that owns the handler

handler - the handler to install

Throws:

IllegalStateException - if a different module already owns the handler

Since:

6.3.1

removeHandler

public void removeHandler(UltiToolsPlugin owner)

Removes the handler when owner is the module that set it; other owners are ignored. After removal, completions are answered as if no handler were registered.

Parameters:

owner - the module that set the handler

Since:

6.3.1