Class AccessControlModule

java.lang.Object
com.hypixel.hytale.server.core.plugin.PluginBase
com.hypixel.hytale.server.core.plugin.JavaPlugin
com.hypixel.hytale.server.core.modules.accesscontrol.AccessControlModule
All Implemented Interfaces:
CommandOwner
public class AccessControlModule extends JavaPlugin
Since:
06.08.2016

  • Field Details

  • Constructor Details

    • AccessControlModule

      public AccessControlModule(@Nonnull JavaPluginInit init)

  • Method Details

    • get

      public static AccessControlModule get()

    • registerAccessProvider

      public void registerAccessProvider(@Nonnull AccessProvider provider)
      Registers a provider that the server asks when a player connects. The first provider with a reason refuses the connection, so the ones after it are never asked.

      A provider stays registered until the server stops, including across an unload of the plugin that registered it.

      Parameters:
      provider - the provider to ask when a player connects

    • getBanProvider

      @Nonnull public BanProvider getBanProvider()
      Returns the ban list the server itself uses, which the configuration names.

      Never construct a second provider over the same storage. Both hold their own copy of it, so the one that saves last discards the bans of the other.

      Returns:
      the ban provider
      Throws:
      IllegalStateException - if the server has yet to resolve it, which it does when it starts. Call this from start rather than setup.

    • setBanProvider

      @Nullable public BanProvider setBanProvider(@Nonnull BanProvider banProvider)
      Replaces the ban list the server uses. Call this from the setup step of a plugin that keeps the bans somewhere else, which wins over the list the configuration names. To let a server name the list instead, register a BanStorageProvider type with its codec.

      If the server has started, the module writes the old provider and reads the new one before the new one goes live. If the read fails, the old provider stays in place. If the server has yet to start, the module reads the new provider when it does.

      The module holds the installed provider until something replaces it, including across an unload of the plugin that installed it. Put the returned provider back with restoreBanProvider(BanProvider, BanProvider) in the shutdown step of that plugin.

      A failure to write the old provider does not stop the swap, because the provider you most need to replace is the one whose storage has gone. To swap only when the old provider writes cleanly, call BanProvider.save() on it first and swap on success.

      Parameters:
      banProvider - the ban provider to use
      Returns:
      the provider that was in place, which still holds the bans it read, or null if the server had yet to resolve one, which is the case in the setup step

    • restoreBanProvider

      public boolean restoreBanProvider(@Nonnull BanProvider banProvider, @Nullable BanProvider previous)
      Puts a provider back, as the shutdown step of a plugin that installed one does.

      Use this rather than setBanProvider(BanProvider), because another plugin may have replaced your provider since you installed it. Putting yours back then would drop theirs, and putting theirs back when they unload would install yours after you have gone.

      Parameters:
      banProvider - the provider you installed, which must still be the one in use
      previous - the provider to put back, which setBanProvider(BanProvider) returned. Pass the null it returns in the setup step, and the module puts back the ban list the configuration names.
      Returns:
      true if the provider was put back, false if something else replaced yours in the meantime, in which case nothing changes

    • isJoinPermissionRequired

      public boolean isJoinPermissionRequired()
      Returns:
      true if a player needs HytalePermissions.SERVER_JOIN to connect

    • setJoinPermissionRequired

      @Nonnull public CompletableFuture<Void> setJoinPermissionRequired(boolean required)
      Sets whether a player needs HytalePermissions.SERVER_JOIN to connect and stores the change in the server configuration. A player who is online stays online, because the requirement only applies when a player connects.

      No group holds the permission, so a server that turns this on refuses every player it has yet to grant it to. An operator keeps their way in through the admin group.

      Parameters:
      required - whether a player needs the permission to connect
      Returns:
      a future that completes when the configuration has been written. If the write fails, the requirement goes back to what it was, so it is either stored or dropped.

    • allowJoin

      public boolean allowJoin(@Nonnull UUID uuid)
      Grants the player the permission they need to connect.
      Parameters:
      uuid - the UUID of the player to allow
      Returns:
      true if the player was granted the permission, false if they already held it as a grant of their own

    • allowJoin

      public int allowJoin(@Nonnull Collection<UUID> uuids)
      Grants every player named the permission they need to connect, as one change.
      Parameters:
      uuids - the UUID of each player to allow
      Returns:
      the number of players that were granted the permission

    • disallowJoin

      public boolean disallowJoin(@Nonnull UUID uuid)
      Takes back the permission the player needs to connect. A player who is online stays online, because the requirement only applies when a player connects.

      This takes back a grant made to the player. A player who holds the permission through a group or a wildcard keeps it, so check isAllowedToJoin(UUID) to see whether the player can still connect.

      Parameters:
      uuid - the UUID of the player to refuse
      Returns:
      true if the player held the permission as a grant of their own

    • disallowAllJoins

      public int disallowAllJoins()
      Takes the permission back from every player that was granted it, as one change.
      Returns:
      the number of players the permission was taken from

    • isAllowedToJoin

      public boolean isAllowedToJoin(@Nonnull UUID uuid)
      Answers the question the server asks when a player connects, so it counts a permission the player holds through a group or a wildcard as well as one granted to them.
      Parameters:
      uuid - the UUID of the player to check
      Returns:
      true if the player may connect while the requirement is on

    • getUsersWithJoinGrant

      @Nonnull public Set<UUID> getUsersWithJoinGrant()
      A player who holds the permission through a group or a wildcard is not listed, because the grant belongs to the group rather than to them. Ask isAllowedToJoin(UUID) for the answer that counts every way of holding it.
      Returns:
      the players that were granted the permission they need to connect

    • isBanned

      public boolean isBanned(@Nonnull UUID uuid)
      Parameters:
      uuid - the UUID of the player to check
      Returns:
      true if the player is banned

    • ban

      public boolean ban(@Nonnull Ban ban)
      Stores the Ban, then disconnects the target if they are online. The store happens before this method returns, and can block, so call it off the world thread.
      Parameters:
      ban - the ban to apply
      Returns:
      true if the ban was applied, false if it has already run out or the target already has one

    • unban

      public boolean unban(@Nonnull UUID uuid)
      Removes any ban on the player. The store happens before this method returns, and can block, so call it off the world thread. An online player is not affected, because a ban only applies when a player connects.
      Parameters:
      uuid - the UUID of the player to unban
      Returns:
      true if the player had a ban

    • getDisconnectReason

      @Nonnull public CompletableFuture<Optional<Message>> getDisconnectReason(@Nonnull UUID uuid)
      Checks access providers in order and returns the first reason to refuse the account. An empty result permits access.

      Connection types that bypass player setup must complete this check before serving requests. Providers can throw before this method returns or complete the returned future exceptionally. Both cases must refuse access. Do not block the channel thread while waiting for a result or cancel the returned future, which providers can share.

      Parameters:
      uuid - the account to check
      Returns:
      the first disconnect reason, or an empty result if all providers permit access