Package com.ultikits.ultitools.utils

Class PlayerLinkChannel

java.lang.Object

com.ultikits.ultitools.utils.PlayerLinkChannel

All Implemented Interfaces:

CloudPlayerLinks.Transport

final class PlayerLinkChannel
extends Object
implements CloudPlayerLinks.Transport

Carries the player-link protocol behind CloudPlayerLinks: it frames player.link.create, correlates the answer by envelope id, delivers completions and expiries to the single owning module, and records each completion result in the shared ledger before answering the gateway.

Pending creates are keyed by the envelope id the channel reports for the frame it just sent. A completion whose create is still pending without an answer waits for that answer so the module sees the link before the completion; a completion that arrives after a restart, with no create pending in this run, is delivered straight away.

Order of a completion result: the result is recorded and persisted in the ledger under the completion's envelope id before the player.link.completed.result frame is handed to the socket. A redelivery of that id finds the recorded result and re-sends it without calling the handler again. A handler that does not answer in time sends nothing, so the gateway redelivers.

The result of a handler call is sent on the connection that is live when the handler finishes, not on the one the completion arrived on: the module may work for seconds, long enough for the socket to be replaced. If no connection is open at that moment, nothing is sent and the persisted receipt answers the next redelivery.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static final class	PlayerLinkChannel.Held	A completion that arrived before its create was answered.
private static final class	PlayerLinkChannel.Owner	The owning module and its handler.
private static final class	PlayerLinkChannel.Pending	One create this run issued and has not answered yet.
private static final class	PlayerLinkChannel.Player	The player fields shared by completions and expiries.

Field Summary

Fields

Modifier and Type	Field	Description
private final Set<String>	busyCompletions
private final Supplier<CloudChannel>	channel
private final LongSupplier	gatewayClockOffsetMillis
private final AtomicReference<PlayerLinkChannel.Owner>	handler
(package private) static final long	HANDLER_DEADLINE_MS	How long the handler may take before the framework stops waiting and sends no result.
private final Executor	handlerThread
private final DedupeLedger	ledger
private static final Pattern	LINK_URL
private static final Logger	LOGGER
private static final long	MAX_CLOCK_VALUE
private final BooleanSupplier	onlineMode
private final Map<String,PlayerLinkChannel.Pending>	pendingCreates
(package private) static final long	REQUEST_DEADLINE_MS	How long the gateway may take to answer one create, or one handler to answer a completion.
private final ShutdownGate.Signal	shutdown
private final ScheduledExecutorService	timers

Constructor Summary

Constructors

Constructor	Description
PlayerLinkChannel(Supplier<CloudChannel> channel, DedupeLedger ledger, BooleanSupplier onlineMode, LongSupplier gatewayClockOffsetMillis, ScheduledExecutorService timers, Executor handlerThread)	Binds the channel to one connection's suppliers and to the shared session ledger.
PlayerLinkChannel(Supplier<CloudChannel> channel, DedupeLedger ledger, BooleanSupplier onlineMode, LongSupplier gatewayClockOffsetMillis, ScheduledExecutorService timers, Executor handlerThread, ShutdownGate.Signal shutdown)

Method Summary

Modifier and Type	Method	Description
private void	answer(CloudChannel connection, String id, com.google.gson.JsonObject result)
private boolean	callHandler(CloudPlayerLinks.LinkEventHandler target, CloudPlayerLinks.LinkCompletion completion, CloudChannel connection, String id, Runnable exit)
private static void	cancel(PlayerLinkChannel.Pending pending)
private CloudPlayerLinks.LinkCompletion	completionOf(CloudRequest request)
CompletableFuture<CloudPlayerLinks.LinkCreation>	create(UltiToolsPlugin requester, UUID playerUuid, String playerName, CloudPlayerLinks.GameAuth gameAuth, Set<CloudPlayerLinks.LinkProof> offeredProofs)	Sends one player.link.create and tracks its answer.
private com.google.gson.JsonObject	createPayload(UUID playerUuid, String playerName, CloudPlayerLinks.GameAuth gameAuth, Set<CloudPlayerLinks.LinkProof> offeredProofs)
private Runnable	deadlineOfCreate(String id)
private void	deliver(CloudPlayerLinks.LinkCompletion completion, CloudChannel connection)	Delivers one completion to the module's handler, or answers it when no handler is set.
private static com.google.gson.JsonObject	errorResult(String code, String message)
private Runnable	exitOnce()
private void	expireCreate(String id)
private static CloudPlayerLinks.ExpiryReason	expiryReason(String reason)
private static CloudPlayerLinks.Failure	failure(String code)
private void	invokeHandler(CloudPlayerLinks.LinkEventHandler target, CloudPlayerLinks.LinkCompletion completion, CloudChannel connection, String id, Runnable exit)
private static com.google.gson.JsonObject	noHandlerResult(CloudPlayerLinks.LinkCompletion completion)
private static CompletableFuture<CloudPlayerLinks.LinkCreation>	notConnected()
private static com.google.gson.JsonObject	okResult(String gameAccount)
(package private) void	onChannelClosed()	Completes every pending create as not connected when the connection closes; held completions are dropped because the gateway redelivers them after the next welcome.
private void	onCompleted(CloudRequest request, CloudChannel connection)
private void	onCreated(CloudRequest request, CloudChannel connection)
(package private) void	onErrorReply(CloudRequest request)	Answers a correlated error reply for a create this run issued.
private void	onExpired(CloudRequest request, CloudChannel connection)
private static PlayerLinkChannel.Player	playerOf(com.google.gson.JsonObject json, String id)
private static List<CloudPlayerLinks.LinkProof>	proofs(com.google.gson.JsonArray array)
(package private) void	register(AgentMessageRouter router)	Registers this channel's handlers for the three link messages and for correlated errors.
void	removeHandler(UltiToolsPlugin owner)	Removes the handler if owner set it.
private static com.google.gson.JsonObject	resultOf(CloudPlayerLinks.GameAccountResult result)
private void	sendResult(CloudChannel connection, String id, com.google.gson.JsonObject result)
void	setHandler(UltiToolsPlugin owner, CloudPlayerLinks.LinkEventHandler handler)	Installs the single-owner handler.
private static String	wireOf(CloudPlayerLinks.LinkProof proof)

Methods inherited from class java.lang.Object

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

Field Details

LOGGER

private static final Logger LOGGER

REQUEST_DEADLINE_MS

static final long REQUEST_DEADLINE_MS

How long the gateway may take to answer one create, or one handler to answer a completion.

See Also:

• Constant Field Values

HANDLER_DEADLINE_MS

static final long HANDLER_DEADLINE_MS

How long the handler may take before the framework stops waiting and sends no result.

See Also:

• Constant Field Values

LINK_URL

private static final Pattern LINK_URL

MAX_CLOCK_VALUE

private static final long MAX_CLOCK_VALUE

See Also:

• Constant Field Values

channel

private final Supplier<CloudChannel> channel

ledger

private final DedupeLedger ledger

onlineMode

private final BooleanSupplier onlineMode

gatewayClockOffsetMillis

private final LongSupplier gatewayClockOffsetMillis

timers

private final ScheduledExecutorService timers

handlerThread

private final Executor handlerThread

shutdown

private final ShutdownGate.Signal shutdown

pendingCreates

private final Map<String,PlayerLinkChannel.Pending> pendingCreates

busyCompletions

private final Set<String> busyCompletions

handler

private final AtomicReference<PlayerLinkChannel.Owner> handler

Constructor Details

PlayerLinkChannel

PlayerLinkChannel(Supplier<CloudChannel> channel,
 DedupeLedger ledger,
 BooleanSupplier onlineMode,
 LongSupplier gatewayClockOffsetMillis,
 ScheduledExecutorService timers,
 Executor handlerThread)

Binds the channel to one connection's suppliers and to the shared session ledger.

Parameters:

channel - supplies the current connection, or null while none exists

ledger - the shared session ledger and synchronization monitor

onlineMode - reports this server's online-mode setting

gatewayClockOffsetMillis - the gateway clock minus the framework clock, in milliseconds

timers - schedules the create and handler deadlines

handlerThread - runs the owning module's handler

PlayerLinkChannel

PlayerLinkChannel(Supplier<CloudChannel> channel,
 DedupeLedger ledger,
 BooleanSupplier onlineMode,
 LongSupplier gatewayClockOffsetMillis,
 ScheduledExecutorService timers,
 Executor handlerThread,
 ShutdownGate.Signal shutdown)

Parameters:

channel - supplies the current connection, or null while none exists

ledger - the shared session ledger and synchronization monitor

onlineMode - reports this server's online-mode setting

gatewayClockOffsetMillis - the gateway clock minus the framework clock, in milliseconds

timers - schedules the create and handler deadlines

handlerThread - runs the owning module's handler

shutdown - the shutdown signal (ShutdownGate): a completion is delivered only with a permit, which is returned when the handler's work and the receipt end (22-23 second verification); refused, the completion is left unanswered for redelivery after the next welcome

Method Details

register

void register(AgentMessageRouter router)

Registers this channel's handlers for the three link messages and for correlated errors.

Parameters:

router - the session's message router

create

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

Description copied from interface: CloudPlayerLinks.Transport

Sends one player.link.create and tracks its answer.

Specified by:

create in interface CloudPlayerLinks.Transport

Parameters:

requester - the calling module

playerUuid - the player's UUID

playerName - the player's name

gameAuth - the game-authentication facts

offeredProofs - the supported proofs

Returns:

the answer future, never null

setHandler

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

Description copied from interface: CloudPlayerLinks.Transport

Installs the single-owner handler.

Specified by:

setHandler in interface CloudPlayerLinks.Transport

Parameters:

owner - the owning module

handler - the handler

removeHandler

public void removeHandler(UltiToolsPlugin owner)

Description copied from interface: CloudPlayerLinks.Transport

Removes the handler if owner set it.

Specified by:

removeHandler in interface CloudPlayerLinks.Transport

Parameters:

owner - the owning module

onChannelClosed

void onChannelClosed()

Completes every pending create as not connected when the connection closes; held completions are dropped because the gateway redelivers them after the next welcome.

deadlineOfCreate

private Runnable deadlineOfCreate(String id)

expireCreate

private void expireCreate(String id)

onCreated

private void onCreated(CloudRequest request,
 CloudChannel connection)

onCompleted

private void onCompleted(CloudRequest request,
 CloudChannel connection)

deliver

private void deliver(CloudPlayerLinks.LinkCompletion completion,
 CloudChannel connection)

Delivers one completion to the module's handler, or answers it when no handler is set. Runs with its own shutdown permit (22-23 second verification), whichever thread delivers it -- the connection thread, the timer of a create's deadline, or the connection thread of a later player.link.created for a held completion -- and returns it only when the handler's work and the receipt have ended; refused, the completion is left for the gateway to deliver again after the next welcome, exactly as ShutdownGate leaves it.

exitOnce

private Runnable exitOnce()

Returns:

a hook that returns this delivery's shutdown permit the first time it runs

invokeHandler

private void invokeHandler(CloudPlayerLinks.LinkEventHandler target,
 CloudPlayerLinks.LinkCompletion completion,
 CloudChannel connection,
 String id,
 Runnable exit)

callHandler

private boolean callHandler(CloudPlayerLinks.LinkEventHandler target,
 CloudPlayerLinks.LinkCompletion completion,
 CloudChannel connection,
 String id,
 Runnable exit)

Returns:

whether the permit now belongs to the handler's future (returned by exit when it settles)

onExpired

private void onExpired(CloudRequest request,
 CloudChannel connection)

onErrorReply

void onErrorReply(CloudRequest request)

Answers a correlated error reply for a create this run issued.

Parameters:

request - the parsed error frame

answer

private void answer(CloudChannel connection,
 String id,
 com.google.gson.JsonObject result)

sendResult

private void sendResult(CloudChannel connection,
 String id,
 com.google.gson.JsonObject result)

notConnected

private static CompletableFuture<CloudPlayerLinks.LinkCreation> notConnected()

createPayload

private com.google.gson.JsonObject createPayload(UUID playerUuid,
 String playerName,
 CloudPlayerLinks.GameAuth gameAuth,
 Set<CloudPlayerLinks.LinkProof> offeredProofs)

completionOf

private CloudPlayerLinks.LinkCompletion completionOf(CloudRequest request)

playerOf

private static PlayerLinkChannel.Player playerOf(com.google.gson.JsonObject json,
 String id)

proofs

private static List<CloudPlayerLinks.LinkProof> proofs(com.google.gson.JsonArray array)

wireOf

private static String wireOf(CloudPlayerLinks.LinkProof proof)

failure

private static CloudPlayerLinks.Failure failure(String code)

expiryReason

private static CloudPlayerLinks.ExpiryReason expiryReason(String reason)

noHandlerResult

private static com.google.gson.JsonObject noHandlerResult(CloudPlayerLinks.LinkCompletion completion)

resultOf

private static com.google.gson.JsonObject resultOf(CloudPlayerLinks.GameAccountResult result)

okResult

private static com.google.gson.JsonObject okResult(String gameAccount)

errorResult

private static com.google.gson.JsonObject errorResult(String code,
 String message)

cancel

private static void cancel(PlayerLinkChannel.Pending pending)