Documentation on query performance and address strictness (#190)

Closes #190 and #192

bans-core/src/it/geyser-support/pom.xml

@@ -100,7 +100,7 @@
     <repositories>
         <repository>
             <id>opencollab-snapshot-repo</id>
-            <url>https://repo.opencollab.dev/snapshot/</url>
+            <url>https://repo.opencollab.dev/maven-snapshots/</url>
             <snapshots>
                 <enabled>true</enabled>
             </snapshots>
@@ -109,4 +109,4 @@
             </releases>
         </repository>
     </repositories>
-</project>
+</project>

docs/Database-Performance.md

@@ -0,0 +1,52 @@
+
+LibertyBans' performance is strongly related to database query performance. Fast database access equates to fast plugin performance.
+
+This page is mostly useful for large servers looking to ensure efficient operation.
+
+### Performance Factors
+
+Performance largely depends on the database queries issued to check incoming players for bans and chatting players for mutes. Every time a player connects to the server, or sends a chat message, a database query is executed. If these queries take longer, connections and chat messages will become delayed.
+
+To reduce database queries issued for chat messages, LibertyBans uses a mute cache. This prevents players chatting frequently from overwhelming the database. The mute cache keeps track of players who recently chatted and whether they are muted.
+
+## Performance Configuration
+
+### Address Strictness
+
+The configured address strictness directly affects query performance. Scalability is the primary concern. If a query is scalable, its execution time will not depend on the quantity of data. For example, a scalable query should yield similar results on a database with 100 punishments as on a database with 100,000 punishments.
+
+Introducing the **Rule of Preservation of Scalability:** In LibertyBans' queries, *scalability* is usually preserved by choosing a stricter level.
+  * This point is crucial. It means that query performance is not dependent on the number of stored punishments.
+  * There is one exception to the Rule of Preservation of Scalability. Using the default HSQLDB database with `STERN` or `STRICT` eliminates scalability of enforcement queries, as investigated in [#190](https://github.com/A248/LibertyBans/issues/190). Large servers are therefore discouraged from using HSQLDB with either `STERN` or `STRICT` settings.
+
+Generally, progressively stricter address strictness options increase execution time. More computational work is necessary to fulfill a greater level of address strictness. However, thanks to the Rule of Preservation of Scalability, this slightly greater per-query execution cost is relatively non-consequential.
+
+### Connection Pool Size
+
+Following recommended technical practice, LibertyBans uses a fixed connection pool. By default, the connection pool is quite small with only 6 connections.
+
+You will likely be surprised to find that a pool of 6 connections can service a large server with many players connecting and chatting. For a large network with LibertyBans installed on the proxy, you may wish to increase the connection pool size.
+
+Please keep in mind that a larger connection pool does not necessarily mean better performance. Too often, administrators make pool sizes too large, which in fact reduces performance. Read [this page](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing) to better understand connection pool sizing.
+
+### Mute Cache Settings
+
+Increasing the mute cache expiration time means mutes will be stored for longer, and therefore, fewer queries will be made to the database.
+
+The expiration semantic does affect performance, but it should be configured on the basis of correct behavior as priority.
+
+## Common Issues
+
+### Network Latency
+
+If your database is slow to respond, that will translate to LibertyBans taking longer to check bans and mutes.
+
+Ensure the database is not located in a geographically distant region (for example, a MySQL database in Antarctica).
+
+### Connection Pool Overload
+
+If you run a large network with LibertyBans installed on the proxy, the default connection pool size may be insufficient to meet your needs. If you repeatedly notice players taking too long to login or chat, try increasing the connection pool size.
+
+If you are familiar debugging, it is fairly easy to investigate connection pool load by using either live debugging tools or logging configuration to monitor connection pool events.
+
+Another solution to an overloaded connection pool is more aggressive mute caching.

docs/Guide-to-Composite-Punishments.md

@@ -18,9 +18,9 @@ You should be familiar with UUIDs and IP addresses, the relation of these to use
 With respect to enforcing punishments, a composite ban is much akin to an IP-ban.
 * Using LENIENT strictness, any user with the banned UUID or the banned address will be banned.
   * Composite bans are thus useful if you desire punishment stricter than a LENIENT IP ban, which bans only players with the address, but not as restricting as a NORMAL IP ban, which bans all players that have ever had that address.
-* Using NORMAL or STRICT strictness, the applicable users are the same as if the ban was an IP ban.
-  * This is because, under NORMAL/STRICT strictness, an IP ban will always apply to the user who had that IP address, so it will be as if the user's UUID was banned too.
-  * Recall the explanations of [NORMAL and STRICT enforcement](Punishment-Enforcement_-Lenient,-Normal,-and-Strict-settings)
+* Using NORMAL, STERN, or STRICT strictness, the applicable users are the same as if the ban was an IP ban.
+  * This is because, under STERN/NORMAL/STRICT strictness, an IP ban will always apply to the user who had that IP address, so it will be as if the user's UUID was banned too.
+  * Recall the explanations of [punishment enforcement](Punishment-Enforcement_-Lenient,-Normal,-and-Strict-settings)
 
 With respect to creating, undoing, and listing punishments with commands, composite bans are arguably easier to use than IP bans.
   * In punishment messages, composite victims are displayed as a username rather than an IP address.

docs/Punishment-Enforcement_-Lenient,-Normal,-and-Strict-settings.md

@@ -1,15 +1,24 @@
 
-Here's how punishments are enforced. I'll use bans in this explanation, but the same can be said for mutes.
+This page explains how punishments are enforced. I'll use bans as an example, but the same can be said for mutes.
+
+Punishment enforcement depends on the `address-strictness` setting you configure.
+
+## Choosing an Address Strictness
+
+The default address strictness is `NORMAL`. The behavior in other punishment plugins is similar to `LENIENT` in LibertyBans.
+
+For large servers, there are also [performance considerations](Database-Performance) to choosing the strictness.
 
 ## User Ban
 
-The ban applies only to the target user. That user may change their name, but they will still be banned according to their UUID.
+On lenient, normal, or stern address strictness:
+* The ban applies only to the target user. That user may change their name, but they will still be banned according to their UUID.
 
-## IP Bans
+On strict strictness, user bans are treated as if IP bans.
 
-How an IP ban is applied depends on the `address-strictness` you configure.
+## IP Bans
 
-Note that if "strict" is used, user bans are treated as if IP bans.
+Behavior depends on the strictness configured.
 
 ### Lenient strictness
 

docs/_sidebar.md

@@ -14,9 +14,10 @@
   * [Versioning and Support Policy](Versioning-and-Support-Policies)
   * [Upgrading 1.0.x -> 1.1.0](Upgrading-to-LibertyBans-1.1.0-from-1.0.x.md) + [Full changelog for 1.1.0](Changes-in-LibertyBans-1.1.0.md)
   * [Upgrading 0.8.x -> 1.0.0](Upgrading-to-LibertyBans-1.0.0-from-0.8.x) + [Full changelog for 1.0.0](Changes-in-LibertyBans-1.0.0)
-* For Developers
+* Technical
   * [Developer API](Developer-API)
   * [The Database Schema](The-Database-Schema)
+  * [Achieving High Performance](Database-Performance)
 * Relations to other software
   * [Importing from other plugins](Importing-from-Other-Plugins)
   * [Dealing with misbehaving plugins](Misbehaving-Plugins)