com.ibasco.agql.protocols.valve.source.query.rcon

Class SourceRconClient

java.lang.Object

com.ibasco.agql.core.AbstractClient<R,S>

com.ibasco.agql.core.NettySocketClient<SourceRconRequest,SourceRconResponse>

com.ibasco.agql.protocols.valve.source.query.rcon.SourceRconClient

All Implemented Interfaces:

Client, Closeable, AutoCloseable

public final class SourceRconClient
extends NettySocketClient<SourceRconRequest,SourceRconResponse>

An RCON client based on Valve's Source RCON Protocol.

Code example:

Asynchronous (non-blocking)

 try (SourceRconClient rconClient = new SourceRconClient()) {
     //status command
     final String command = "status";
     //authenticate + execute
     CompletableFuture<SourceRconCmdResponse> responseFuture = rconClient.authenticate(serverAddress, password.getBytes())
                                                                         .thenCompose(authResponse -> {
                                                                             if (!authResponse.isAuthenticated())
                                                                                 throw new CompletionException(String.format("Failed to authenticate address '%s' (Reason: %s)", authResponse.getAddress(), authResponse.getReason()), authResponse.getAddress());
                                                                             return rconClient.execute(authResponse.getAddress(), command);
                                                                         });
     //Check future if completed
     if (responseFuture.isDone()) {
         SourceRconCmdResponse response = responseFuture.getNow(null);
         System.out.println("RESPONSE: " + response.getResult());
     }
     //Register callback if not yet complete
     else {
         responseFuture.whenComplete((response, error) -> {
             if (error != null) {
                 error.printStackTrace(System.err);
                 return;
             }
             assert response != null;
             System.out.println(response.getResult());
         });
     }
 }
 

Synchronous (blocking)

 try (SourceRconClient rconClient = new SourceRconClient()) {
     //status command
     final String command = "status";
     //authenticate + execute
     SourceRconCmdResponse response = rconClient.authenticate(serverAddress, password.getBytes())
                                                .thenCompose(authResponse -> {
                                                    if (!authResponse.isAuthenticated())
                                                        throw new CompletionException(String.format("Failed to authenticate address '%s' (Reason: %s)", authResponse.getAddress(), authResponse.getReason()), authResponse.getAddress());
                                                    return rconClient.execute(authResponse.getAddress(), command);
                                                }).join();
     System.out.println("RESPONSE: " + response.getResult());
 }
 

Author:

Rafael Luis Ibasco

See Also:

Source RCON Protocol Specifications, SourceRconOptions

Constructor Summary

Constructors

Constructor and Description
SourceRconClient() Create a new instance using the pre-defined configuration Options for this client
SourceRconClient(SourceRconOptions options) Create a new instance using the provided configuration SourceRconOptions

Method Summary

Modifier and Type	Method and Description
CompletableFuture<SourceRconAuthResponse>	authenticate(InetSocketAddress address) Re-authenticate a previously registered address.
CompletableFuture<SourceRconAuthResponse>	authenticate(InetSocketAddress address, byte[] passphrase) Sends an authentication request to the specified address.
void	cleanup() Request to release/close inactive connections.
void	cleanup(boolean force) Request to release/close connections
protected NettyMessenger<SourceRconRequest,SourceRconResponse>	createMessenger(Options options) Factory method for Messenger.
CompletableFuture<SourceRconCmdResponse>	execute(InetSocketAddress address, String command) Sends a command request to the server
protected SourceRconMessenger	getMessenger() Getter for the field messenger.
com.google.common.collect.SetMultimap<InetSocketAddress,SourceRconMessenger.ConnectionStats>	getStatistics() Rcon connection statistics
void	invalidate() Invalidates only the connections of all registered address (registered via authenticate(InetSocketAddress, byte[])).
void	invalidate(boolean onlyConnections) Invalidates only the connections of all registered address (registered via authenticate(InetSocketAddress, byte[])).
void	invalidate(InetSocketAddress address) Invalidates the specified address along with the previously authenticated connections.
boolean	isAuthenticated(InetSocketAddress address) Checks if the specified address is authenticated
void	printConnectionStats(Consumer<String> output)
void	printExecutorStats(Consumer<String> output)
protected <V extends SourceRconResponse> CompletableFuture<V>	send(InetSocketAddress address, SourceRconRequest request, Class<V> expectedResponse) Send request.

Methods inherited from class com.ibasco.agql.core.NettySocketClient

close, equals, getExecutor, hashCode

Methods inherited from class com.ibasco.agql.core.AbstractClient

getOptions, id, send

Methods inherited from class java.lang.Object

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

Constructor Detail

SourceRconClient

public SourceRconClient()

Create a new instance using the pre-defined configuration Options for this client

SourceRconClient

public SourceRconClient(SourceRconOptions options)

Create a new instance using the provided configuration SourceRconOptions

Parameters:

options - The Options instance containing the user-defined configuration options.

See Also:

Options, SourceRconOptions, OptionBuilder

Method Detail

authenticate

public CompletableFuture<SourceRconAuthResponse> authenticate(InetSocketAddress address,
                                                              byte[] passphrase)

Sends an authentication request to the specified address. If successful, the credentials is then registered and the underlying connection is now managed internally. You will only need to call this once unless it has been invalidated. Use isAuthenticated(InetSocketAddress) to check if the credentials of the address is still valid.

WARNING: By default, the credentials stored in-memory are not encrypted, however you can implement and provide your own custom CredentialsStore which can be set via configuration.

Parameters:

address - The address of the source server

passphrase - The rcon passphrase in byte array form

Returns:

A CompletableFuture when completed, returns a SourceRconAuthResponse that holds the status of the authentication request.

Throws:

IllegalArgumentException - If the address or password supplied is empty or null

See Also:

SourceRconOptions.CREDENTIALS_STORE, CredentialsStore, Credentials, isAuthenticated(InetSocketAddress)

send

protected <V extends SourceRconResponse> CompletableFuture<V> send(InetSocketAddress address,
                                                                   SourceRconRequest request,
                                                                   Class<V> expectedResponse)

Send request.

Overrides:

send in class AbstractClient<SourceRconRequest,SourceRconResponse>

Type Parameters:

V - a V class

Parameters:

address - a InetSocketAddress object

request - a R object

expectedResponse - a Class object

Returns:

a CompletableFuture object

authenticate

public CompletableFuture<SourceRconAuthResponse> authenticate(InetSocketAddress address)

Re-authenticate a previously registered address. The address should be authenticated (via authenticate(InetSocketAddress, byte[])) and the credentials should still be valid, or the returned future will fail. Use isAuthenticated(InetSocketAddress) to check if the address is authenticated and registered.

Parameters:

address - The address of the source server

Returns:

A CompletableFuture when completed, returns a SourceRconAuthResponse which holds the status of the authentication request.

Throws:

RconNotYetAuthException - If the address has not yet been authenticated by the server

See Also:

authenticate(InetSocketAddress, byte[])

isAuthenticated

public boolean isAuthenticated(InetSocketAddress address)

Checks if the specified address is authenticated

Parameters:

address - An InetSocketAddress representing the server

Returns:

true if the address has been successfully been authenticated by the remote server

See Also:

authenticate(InetSocketAddress, byte[])

execute

public CompletableFuture<SourceRconCmdResponse> execute(InetSocketAddress address,
                                                        String command)
                                                 throws RconAuthException

Sends a command request to the server

Parameters:

address - The InetSocketAddress of the source server

command - The String containing the command to be issued on the server

Returns:

A CompletableFuture which contains a response String returned by the server

Throws:

RconAuthException - If the address is not yet authenticated by the server.

See Also:

authenticate(InetSocketAddress, byte[])

invalidate

public void invalidate()

Invalidates only the connections of all registered address (registered via authenticate(InetSocketAddress, byte[])). The credentials registered with the address will remain valid. You do not need to call authenticate(InetSocketAddress, byte[]) unless the Credentials have been invalidated.

See Also:

authenticate(InetSocketAddress, byte[])

invalidate

public void invalidate(boolean onlyConnections)

Invalidates only the connections of all registered address (registered via authenticate(InetSocketAddress, byte[])). The credentials registered with the address will remain valid. You do not need to call authenticate(InetSocketAddress, byte[]) unless the Credentials have been invalidated.

Parameters:

onlyConnections - true if we should only invalidate the Channel's for the specified address.

See Also:

authenticate(InetSocketAddress, byte[])

invalidate

public void invalidate(InetSocketAddress address)

Invalidates the specified address along with the previously authenticated connections. Once invalidated, the credentials associated with the address will be invalidated and cleared, so you will have to call authenticate(InetSocketAddress, byte[]) again.

Parameters:

address - The InetSocketAddress to invalidate.

See Also:

authenticate(InetSocketAddress, byte[])

cleanup

public void cleanup()

Request to release/close inactive connections. This is similar to calling cleanup(false)

See Also:

cleanup(boolean)

cleanup

public void cleanup(boolean force)

Request to release/close connections

Parameters:

force - true to force release/close all connections, otherwise false to only release/close inactive connections.

See Also:

cleanup()

getStatistics

@ApiStatus.Experimental
public com.google.common.collect.SetMultimap<InetSocketAddress,SourceRconMessenger.ConnectionStats> getStatistics()

Rcon connection statistics

Returns:

A Multimap containing statistical information about the active connections for each registered address

printExecutorStats

@ApiStatus.Experimental
public void printExecutorStats(Consumer<String> output)

printConnectionStats

@ApiStatus.Experimental
public void printConnectionStats(Consumer<String> output)

createMessenger

protected NettyMessenger<SourceRconRequest,SourceRconResponse> createMessenger(Options options)

Factory method for Messenger.

Specified by:

createMessenger in class NettySocketClient<SourceRconRequest,SourceRconResponse>

Parameters:

options - a Options object

Returns:

a Messenger object

getMessenger

protected SourceRconMessenger getMessenger()

Getter for the field messenger.

Overrides:

getMessenger in class NettySocketClient<SourceRconRequest,SourceRconResponse>

Returns:

a Messenger object