mirror of
https://github.com/AuthMe/AuthMeReloaded.git
synced 2025-02-19 21:32:31 +01:00
Merge branch 'master' of https://github.com/AuthMe/AuthMeReloaded.wiki into xephwiki
# Conflicts: # Home.md
ljacqu
commit
54feb1f471
3
'please-verify'-Label.md
Normal file
3
'please-verify'-Label.md
Normal file
@ -0,0 +1,3 @@
|
||||
We use a `please-verify` label on issues to communicate to the reporter of the issue that we think we have solved his bug or satisfied his question. It's an invitation for the bug reporter to _close_ the issue if it's done, or to tell us what is still missing or unclear.
|
||||
|
||||
Issues with a `please-verify` label can be closed by a developer if the issue reporter doesn't give any feedback within 9 days. This helps us keeping track of which issues still require work.
|
||||
48
5.2-Changelog.md
Normal file
48
5.2-Changelog.md
Normal file
@ -0,0 +1,48 @@
|
||||
This page lists all major changes introduced in AuthMe 5.2. It's a summarized list of all [closed issues in the 5.2 milestone](https://github.com/Xephi/AuthMeReloaded/milestone/1?closed=1). To see which changes may require an action on your side, please see [Breaking Changes](Breaking-Changes).
|
||||
|
||||
|
||||
**Shiny new features**
|
||||
- Temp ban IP after too many wrong logins ([#192](https://github.com/Xephi/AuthMeReloaded/issues/192))
|
||||
- Block tab auto completion for unlogged players ([#390](https://github.com/Xephi/AuthMeReloaded/issues/390))
|
||||
- Bypass the purge with a permission ([#674](https://github.com/Xephi/AuthMeReloaded/issues/674))
|
||||
- /logout invalidates a player's session ([#816](https://github.com/Xephi/AuthMeReloaded/issues/816))
|
||||
- Allow AuthMe to run in sync or async (configurable) ([#937](https://github.com/Xephi/AuthMeReloaded/issues/937))
|
||||
- Show one's own alts on login ([#423](https://github.com/Xephi/AuthMeReloaded/issues/423))
|
||||
- Translatable help section ([#293](https://github.com/Xephi/AuthMeReloaded/issues/293))
|
||||
- Integration with IPB4 ([#483](https://github.com/Xephi/AuthMeReloaded/issues/483))
|
||||
- Run a custom command when more than x alts are detected ([#459](https://github.com/Xephi/AuthMeReloaded/issues/459))
|
||||
- Allow to change the message when a player joins ([#1044](https://github.com/Xephi/AuthMeReloaded/issues/1044))
|
||||
- Support specific legacy hashes ([#850](https://github.com/Xephi/AuthMeReloaded/issues/850))
|
||||
- MySQL to SQLite converter ([[#933](https://github.com/Xephi/AuthMeReloaded/issues/933)](https://github.com/Xephi/AuthMeReloaded/issues/933))
|
||||
- Command for updating the messages file ([#768](https://github.com/Xephi/AuthMeReloaded/issues/768))
|
||||
- Registering with password and email is possible (/register [pass] [email]) ([#427](https://github.com/Xephi/AuthMeReloaded/issues/427))
|
||||
- Deprecate flat file: use SQLite instead ([#344](https://github.com/Xephi/AuthMeReloaded/issues/344))
|
||||
|
||||
**Improve email recovery**
|
||||
- Confirm email recovery before resetting user's password ([#472](https://github.com/Xephi/AuthMeReloaded/issues/472))
|
||||
- Create /email show command ([#922](https://github.com/Xephi/AuthMeReloaded/issues/922))
|
||||
- Fix display of Chinese characters ([#269](https://github.com/Xephi/AuthMeReloaded/issues/269))
|
||||
- Add support for oAuth2 ([#260](https://github.com/Xephi/AuthMeReloaded/issues/260))
|
||||
|
||||
**Improve AntiBot**
|
||||
- Make startup time of Antibot configurable ([#970](https://github.com/Xephi/AuthMeReloaded/issues/970))
|
||||
- Update AntiBot configuration on /authme reload ([#896](https://github.com/Xephi/AuthMeReloaded/issues/896))
|
||||
- Show AntiBot message only to players with permission ([#904](https://github.com/Xephi/AuthMeReloaded/issues/904))
|
||||
- Technical: better implementation of user count in time span ([#938](https://github.com/Xephi/AuthMeReloaded/issues/938))
|
||||
|
||||
**Password storage**
|
||||
- Add support for phpBB 3.1.5 ([#150](https://github.com/Xephi/AuthMeReloaded/issues/150))
|
||||
- Fix broken hash algorithms ([#369](https://github.com/Xephi/AuthMeReloaded/issues/369), [#685](https://github.com/Xephi/AuthMeReloaded/issues/685))
|
||||
|
||||
**Other improvements**
|
||||
- Improve behavior of AuthMe for optional registration ([#611](https://github.com/Xephi/AuthMeReloaded/issues/611))
|
||||
|
||||
**Technical issues**
|
||||
- SQL: always use prepared statements ([#308](https://github.com/Xephi/AuthMeReloaded/issues/308))
|
||||
- refactor command handling ([#305](https://github.com/Xephi/AuthMeReloaded/issues/305), [#306](https://github.com/Xephi/AuthMeReloaded/issues/306))
|
||||
- redesign and test hash algorithm interfaces ([#358](https://github.com/Xephi/AuthMeReloaded/issues/358), [#364](https://github.com/Xephi/AuthMeReloaded/issues/364))
|
||||
- new configuration management ([#347](https://github.com/Xephi/AuthMeReloaded/issues/347)) -> birth of ConfigMe ([#927](https://github.com/Xephi/AuthMeReloaded/issues/927))
|
||||
- distribute workload during purge process better ([#696](https://github.com/Xephi/AuthMeReloaded/issues/696))
|
||||
- apply dependency injection ([#432](https://github.com/Xephi/AuthMeReloaded/issues/432))
|
||||
- integration tests for SQLite and MySQL ([#392](https://github.com/Xephi/AuthMeReloaded/issues/392))
|
||||
- improve how /authme reload works ([#704](https://github.com/Xephi/AuthMeReloaded/issues/704))
|
||||
50
AuthMe-Coding-Styleguide.md
Normal file
50
AuthMe-Coding-Styleguide.md
Normal file
@ -0,0 +1,50 @@
|
||||
- Use indentation of four spaces (not tabs)
|
||||
- Always wrap structures like `if`, `while` with braces (never `if (isTrue) doThis();`)
|
||||
- Fields should not be public – use getters and setters where appropriate
|
||||
- Max line width: 120 characters
|
||||
|
||||
As usual in Java:
|
||||
- Class names should be uppercase and in CamelCase
|
||||
- Names of methods, fields and variables in lowercase and camelCase
|
||||
|
||||
## Exception handling
|
||||
Do not "swallow" exceptions unless an exception is part of an expected scenario that is handled otherwise. Elsewhere you can log the exception with the `ConsoleLogger` easily:
|
||||
|
||||
```java
|
||||
try {
|
||||
Files.write(configFile, settings);
|
||||
} catch (IOException e) {
|
||||
ConsoleLogger.logException("Could not write to config file:", e);
|
||||
}
|
||||
```
|
||||
|
||||
This will output something like: `[WARN] Could not write to config file: [IOException] File is read-only` to the console and the log file. Logging exceptions tremendously helps debugging and helps detecting problems as they occur in the future.
|
||||
|
||||
## Complexity
|
||||
Try to create "bite-sized" elements: a method should do exactly one thing, and a class should solve one main problem. If too many things are done in one method too much brain power gets lost on understanding at what point you are in the method, and you lose a higher level overview that would allow you to find improvements or flaws in the logic.
|
||||
|
||||
## Maintainability
|
||||
Program for an audience – let others benefit from the effort you've spent in analyzing a problem by writing comments and JavaDoc for code that is not obvious:
|
||||
|
||||
```java
|
||||
// Schedule the task to run later so it doesn't interfere with the inventory process
|
||||
scheduler.scheduleSyncTaskLater(new LoginTask());
|
||||
```
|
||||
|
||||
Similarly, create issues in the issue tracker for larger problems or improvements instead of just writing a TODO comment. TODO comments are guaranteed to get forgotten if they are not actively tended to.
|
||||
|
||||
## JavaDoc
|
||||
Use the third person ("Gets the player's name") or the imperative mood ("Get the player's name"); it should be consistent within a class. JavaDoc should briefly explain what the method does and provide additional information to the developer.
|
||||
|
||||
Put an empty line between the description and the first `@param`.
|
||||
|
||||
Example:
|
||||
```java
|
||||
/**
|
||||
* Adds a permission node required to execute this command.
|
||||
*
|
||||
* @param permissionNode the permission node to add
|
||||
* @return true on success, false on failure
|
||||
*/
|
||||
public boolean addPermissionNode(String permissionNode)
|
||||
```
|
||||
18
AuthMe-Releases-(Jenkins).md
Normal file
18
AuthMe-Releases-(Jenkins).md
Normal file
@ -0,0 +1,18 @@
|
||||
You can get the latest versions ("Dev versions") of AuthMe from Jenkins:
|
||||
|
||||
- [AuthMeReloaded Dev Jenkins](http://ci.xephi.fr/job/AuthMeReloaded/) – run after every change
|
||||
|
||||
#### Which JAR file to choose
|
||||
We build AuthMe in three different formats:
|
||||
- AuthMe-...-**legacy**.jar — for Minecraft 1.7.10 and Cauldron (contains required version of Google Guava)
|
||||
- AuthMe-...-**spigot**.jar – typically what you want if the _legacy_ JAR doesn't apply to you
|
||||
- AuthMe-...-**noshade**.jar – for developers only; this is the project without any shaded dependencies
|
||||
|
||||
|
||||
#### How to find the downloads
|
||||
The panel "Build history" on the left shows the latest _builds_; if there is a blue circle next to the number, it means that the code could be successfully converted to a .jar file that you can use for your server.
|
||||
|
||||
Clicking on the build number will allow you to download the JAR file that was generated, allowing you to take the latest changes (e.g. Click on #347 and download the appropriate .jar file under "Build artifacts").
|
||||
|
||||
Remember: the Jenkins runs after _every_ change, which means it may fix recent bugs but it may introduce new issues as well.
|
||||
|
||||
40
Breaking-Changes.md
Normal file
40
Breaking-Changes.md
Normal file
@ -0,0 +1,40 @@
|
||||
This page contains a list of _breaking changes_, i.e. of changes in AuthMe that may require plugin users to make adjustments.
|
||||
|
||||
Version | Description
|
||||
----------------------------- | ----------
|
||||
5.3 ([2017-03-24](https://github.com/AuthMe/AuthMeReloaded/commit/2f90a45f4351d80c4b04d5ca9d07f3ebf2ed62d6)) | `removeSpeed` option no longer exists; speed is removed from unauthenticated players if `allowMovement` is `false`
|
||||
5.3 ([2017-03-12](https://github.com/AuthMe/AuthMeReloaded/commit/8557621c02c13c9b172302f547ad0180d9fe64ac)) | `SaveQuitLocation: false` no longer restores the quit location for players (as the setting would suggest)
|
||||
5.2 ([2017-01-07](https://github.com/AuthMe/AuthMeReloaded/commit/385f7d6b1d13cba58d7446cf6b7e9762fca88e09)) | In the messages file, `reg_email_msg` no longer exists. Update `reg_msg` with the proper arguments.
|
||||
5.2 ([2016-11-13](https://github.com/AuthMe/AuthMeReloaded/commit/bb89a59a8a3db9be6a2c0a0f8eab5a22f1b10abb)) | To support old hashes, you now need to list the hashes in the setting `legacyHashes`
|
||||
5.2 ([2016-09-04](https://github.com/AuthMe/AuthMeReloaded/commit/5efed1b697e03785bba5f96dbc3af69f82b0a28a)) | Dropped support for Java 7
|
||||
5.2 ([2016-09-04](https://github.com/AuthMe/AuthMeReloaded/commit/7deb75ab856250ef84934d578960b4850a313ec8)) | Permissions: support for GroupManager (not via Vault) removed.
|
||||
5.2 ([2016-08-11](https://github.com/AuthMe/AuthMeReloaded/commit/67d53d0c3c98282b645894a0e7eadaf8cbedcbc7)) | In messages_xx.yml files, `&n` is now the regular format code and `%nl%` is replaced to new line
|
||||
5.2 ([2016-06-19](https://github.com/AuthMe/AuthMeReloaded/commit/e1d697d386a1cd94fd09a02654cd7d9eaf854cfe)) | Allowed nickname regex pattern now case-sensitive
|
||||
5.2 ([2016-05-29](https://github.com/AuthMe/AuthMeReloaded/commit/52c0c7dd640217572d32587237abedb9cc35fca3)) | "Allow all commands if registration is optional" feature dropped
|
||||
5.2 ([2016-05-03](https://github.com/AuthMe/AuthMeReloaded/commit/0ea95fb93c5b8408d6cb34c8de381dbce06060d5)) | Force spawn settings are grouped together (settings should migrate automatically)
|
||||
5.2 ([2016-02-19](https://github.com/AuthMe/AuthMeReloaded/commit/715622826f1e67ec50c63fadab90ffdbef1c468f)) | Command /converter has been moved to /authme converter
|
||||
5.2 ([2016-02-14](https://github.com/AuthMe/AuthMeReloaded/commit/b3734f40102466ef145e5361b6125ed96360ddef)) | Some permissions have been moved outside of `authme.player`. Please see the list below.
|
||||
5.2 ([2016-02-12](https://github.com/Xephi/AuthMeReloaded/issues/512)) | `Settings.delayJoinLeaveMessages` has been split up in more granular configurations. Your config file will update automatically, search for options with "delay"
|
||||
5.2 ([2015-12-28](https://github.com/AuthMe/AuthMeReloaded/commit/0688a8645a31e61f2055227e1bd63d2b5bb8859a)) | PlainText is automatically change to SHA256 HashAlgorithm
|
||||
5.2 ([2015-12-26](https://github.com/AuthMe/AuthMeReloaded/commit/41e400e9dd9c6a5194bb739d022d81d004a4159d)) | Flatfile data source and converters _to_/_from_ flatfile no longer supported. Use Sqlite.
|
||||
5.2 ([2015-12-23](https://github.com/AuthMe/AuthMeReloaded/commit/8bfb56f34e010a96107bd435b94ce7bd7fc527fd)) | Setting `settings.restrictions.enablePasswordVerifier` renamed to `enablePasswordConfirmation`
|
||||
5.2 ([2015-12-22](https://github.com/AuthMe/AuthMeReloaded/commit/8f098933371767130b2a533ec9ad0f6075c2522b)) | email.html: Placeholders are like `<playername />`, not `<playername>` or `%playername%`. ([Template](https://github.com/AuthMe/AuthMeReloaded/blob/18dbcfde890ac2c756c3d3ff387007ae00733f52/src/main/resources/email.html))
|
||||
5.1 ([2015‑12‑05](https://github.com/AuthMe/AuthMeReloaded/commit/f1c3eed0699e15640731c4cd06f5feb198ef6553)) | Changed permission nodes ([up-to-date list](https://github.com/AuthMe/AuthMeReloaded/blob/master/src/tools/docs/permission_nodes.md))
|
||||
5.1 ([2015-12-04](https://github.com/AuthMe/AuthMeReloaded/commit/e781115d7cf66db57a436de8d21693aa05d50be3)) | Configurable text sent in email moved from config.yml to email.html
|
||||
5.1 ([2015-11-27](https://github.com/AuthMe/AuthMeReloaded/commit/67244d5e7bf45b58323fdd9808afe5d245d67c66)) | Bug fix: Using /authme register no longer changes the password to all lower-case
|
||||
|
||||
---
|
||||
|
||||
### Addendum
|
||||
|
||||
##### Permissions change 2016-02-14
|
||||
A few permissions were moved outside of the `authme.player` group. The reason was that assigning `authme.player.*` to players also gave them VIP status (`authme.player.vip`), for instance, which was undesired.
|
||||
|
||||
Old permission -> new permission
|
||||
```
|
||||
authme.player.allow2accounts -> authme.allowmultipleaccounts
|
||||
authme.player.bypassantibot -> authme.bypassantibot
|
||||
authme.player.bypassforcesurvival -> authme.bypassforcesurvival
|
||||
authme.player.seeotheraccounts -> authme.admin.seeotheraccounts
|
||||
authme.player.vip -> authme.vip
|
||||
```
|
||||
46
Build-History.md
Normal file
46
Build-History.md
Normal file
@ -0,0 +1,46 @@
|
||||
History of build numbers and the commit that initiated the build on [Jenkins](http://ci.xephi.fr/job/AuthMeReloaded/), for future reference.
|
||||
|
||||
|
||||
Build nr. | Commit
|
||||
--------- | --------------
|
||||
1600 | https://github.com/AuthMe/AuthMeReloaded/commit/1da74cb987c0c8c472d0373f2a730eea549c430a
|
||||
1580 | https://github.com/AuthMe/AuthMeReloaded/commit/c079f5f3d56ace12f5592693450ca8cb9d7fd625
|
||||
1560 | https://github.com/AuthMe/AuthMeReloaded/commit/ef1d006cdfa01eee9c3c835247598976d89be06a
|
||||
1540 | https://github.com/AuthMe/AuthMeReloaded/commit/12566f03ef4a4541a5e5ab7e46834581895518f7
|
||||
1520 | [fe86299](https://github.com/AuthMe/AuthMeReloaded/commit/fe86299c7dada3a1c492789b926ca1f54429e345)
|
||||
1500 | [3604c70](https://github.com/AuthMe/AuthMeReloaded/commit/3604c70a54e6eee8c1230c0a7aad55e1f4b57637)
|
||||
1480 | [2bd5fcd](https://github.com/AuthMe/AuthMeReloaded/commit/2bd5fcde3c981ca35d730f78feae3898d8646351)
|
||||
1460 | [e9f274a](https://github.com/AuthMe/AuthMeReloaded/commit/e9f274aa89550de98e0fcd119b732185790c6d64)
|
||||
1440 | [b3e276d](https://github.com/AuthMe/AuthMeReloaded/commit/b3e276d277765ca4fd2f007236caf7b08e9e8b6e)
|
||||
1420 | [3dab5cd](https://github.com/AuthMe/AuthMeReloaded/commit/3dab5cd70ce6e391381ac3244f00540f303d9b3e)
|
||||
1400 | [7394e00](https://github.com/AuthMe/AuthMeReloaded/commit/7394e004ce3c40da5624f551b2b6390e0ad4fabf)
|
||||
1380 | [ff9f50f](https://github.com/AuthMe/AuthMeReloaded/commit/ff9f50f63f1a80f9f555234d5ee18689cf8a8bff)
|
||||
1370 | [0aa02b7](https://github.com/AuthMe/AuthMeReloaded/commit/0aa02b70f0f6d46344d9c703dccb700a662e9c6f)
|
||||
1360 | [71c289f](https://github.com/AuthMe/AuthMeReloaded/commit/71c289f2f366ba84c311cb32a316c393cf58a986)
|
||||
1350 | -
|
||||
1340 | -
|
||||
1330 | [8327421](https://github.com/AuthMe/AuthMeReloaded/commit/8327421dd41ea730bcc1fe76d0f9ea6c41d5bcf4)
|
||||
1320 | [bc9d67a](https://github.com/AuthMe/AuthMeReloaded/commit/bc9d67abbd7f2d42c028ead9f5a9d9ad73c31d85)
|
||||
1310 | [945c9e9](https://github.com/AuthMe/AuthMeReloaded/commit/945c9e9587e5b58ddef33ecedd4f25662ae0f206)
|
||||
1300 | [b07e60a](https://github.com/AuthMe/AuthMeReloaded/commit/b07e60a807aa7ebccc0d06ba6d8a86f8a0b237c4)
|
||||
1290 | [14900d8](https://github.com/AuthMe/AuthMeReloaded/commit/14900d84fa403d2b9dcdb300ba5bf059af60fdef)
|
||||
1280 | [87d36f6](https://github.com/AuthMe/AuthMeReloaded/commit/87d36f69cf4469b6b654769a4972d36eb20a7dce)
|
||||
1270 | [1681863](https://github.com/AuthMe/AuthMeReloaded/commit/168186321c08c443440035678c91cb201cdc08a4)
|
||||
1260 | [af48c2f](https://github.com/AuthMe/AuthMeReloaded/commit/af48c2fc2aa66c00bb319e1a128d8b431d8ea03e)
|
||||
1250 | [80337f7](https://github.com/AuthMe/AuthMeReloaded/commit/80337f758b234c28af14e32fe1b33cc9eb3f8e8a)
|
||||
1240 | [7fc1953](https://github.com/AuthMe/AuthMeReloaded/commit/7fc195336f9afde3f1baf4ca97eb94d4ad02c752)
|
||||
1230 | [0eb1890](https://github.com/AuthMe/AuthMeReloaded/commit/0eb1890cf9f06eb4a2410bcd2f65ef150a76ac92)
|
||||
1220 | [674a051](https://github.com/AuthMe/AuthMeReloaded/commit/674a051586d3b71f5b32f5dc5a4117d7fb0ff057)
|
||||
1210 | [724de1e](https://github.com/AuthMe/AuthMeReloaded/commit/724de1e1210ed6710efa0ff40c4dcd567ee6ef1b)
|
||||
1200 | [8d54557](https://github.com/AuthMe/AuthMeReloaded/commit/8d54557f3d45fac0d92e036b7feb24748df24693)
|
||||
1190 | [faddb3f](https://github.com/AuthMe/AuthMeReloaded/commit/faddb3ffac0a64d8f82d41361e2c3d1dc537ed5a)
|
||||
1180 | [8f58178](https://github.com/AuthMe/AuthMeReloaded/commit/8f5817883ea3fcc5b4b02e8636f83652e9453b7c)
|
||||
1170 | [de3f3a4](https://github.com/AuthMe/AuthMeReloaded/commit/de3f3a42ab96a814feb32703df0fd4538861db42)
|
||||
1160 | [23836cd](https://github.com/AuthMe/AuthMeReloaded/commit/23836cda6aaff3bd7300f34e00bec2eae42047a5)
|
||||
1150 | [74095fe](https://github.com/AuthMe/AuthMeReloaded/commit/74095fec710acccec9b0aeaeb8a581dd53194322)
|
||||
1140 | [c79857c](https://github.com/AuthMe/AuthMeReloaded/commit/c79857cc14e0630feea5d42d8a9eb0e46d8f547e)
|
||||
1130 | [5cbb83e](https://github.com/AuthMe/AuthMeReloaded/commit/5cbb83e15337a2c88ce4cdb52878f8e64f605ec6)
|
||||
|
||||
Regex replacement for link (Notepad++):
|
||||
- Find: ` (https?://.*?AuthMeReloaded/commit/([0-9a-f]{7})[0-9a-f]{33})`
|
||||
- Replace: ` [\2]\(\1\)`
|
||||
29
Command-Handling.md
Normal file
29
Command-Handling.md
Normal file
@ -0,0 +1,29 @@
|
||||
This page is a technical description of how the commands of AuthMe are registered and handled.
|
||||
|
||||
### Overview
|
||||
The following overview shows the most important players in the command handling process.
|
||||
|
||||
|
||||
|
||||
|
||||
### Command registration
|
||||
We use `CommandDescription` objects to define the commands available in AuthMe. These objects do not contain any logic of the command but contain all of the necessary information to invoke the command it describes: the labels to access the command (e.g. must use `/authme register` or `/authme reg`), the necessary number of arguments and a reference to the actual command implementation.
|
||||
|
||||
### Mapping of incoming commands
|
||||
When a command is invoked, Bukkit (or Spigot) passes the information to the plugin with the arguments `String commandLabel, String[] args`. The Bukkit command label simply contains the first "word" of a command (e.g. `authme` in `/authme reload`) and the Bukkit arguments are the rest.
|
||||
|
||||
In AuthMe, we call _labels_ any tokens at the beginning that lead to a command, so e.g. in `/authme register billy pass123` the labels are `authme, register` as they lead to the admin register command. In the beginning, we don't know what is a label and what is an argument yet, so we collectively refer to them as _command parts_.
|
||||
|
||||
The first job is to determine which of the _parts_ are _labels_ and _arguments_. If the parts could be mapped to a command description and the number of arguments is valid according to the CommandDescription, we speak of a successful mapping. For example, `/authme register billy pass123` leads to the command description for the admin registration command and leaves us with the arguments `billy, pass123`. The command description defines two mandatory arguments, so the argument count matched and we have a successful mapping.
|
||||
|
||||
**Safe assumption:** It is safe to assume while programming that there will be at most 2 labels to access a command (such as `/authme register`, whereas `/authme user register` – with three labels – cannot occur). Any more would unnecessarily complicate our command structure and our code. There is a test verifying that no command description is initialized with more than two labels. Nevertheless, you are still encouraged to write logic related to labels generically if it is not a lot more complicated.
|
||||
|
||||
### Permissions check
|
||||
Permission-related logic is handled in the `permission` package. The CommandHandler class passes the command sender and the command description to the PermissionsManager to query whether the user may invoke the command.
|
||||
|
||||
### Invocation of the command
|
||||
If the permissions check is successful, the command can be invoked. Each command description has a subclass of `ExecutableCommand` linked to it which is the class for actually executing the command logic. The arguments are passed to it.
|
||||
|
||||
An `ExecutableCommand` instance may call further objects, typically for asynchronous processing when database calls are involved. In such cases, the `ExecutableCommand` typically does as much validation as necessary which doesn't require I/O operations (e.g. does the password confirmation match?, is the player online?) and then passes the data on to an async task which handles interactions with the database.
|
||||
|
||||
**Safe assumption:** Within an `ExecutableCommand`, it is safe to assume that all mandatory arguments defined in the corresponding command description(s) are present. The command handler will not execute a command if the argument count does not match.
|
||||
7
Configuring-logging.md
Normal file
7
Configuring-logging.md
Normal file
@ -0,0 +1,7 @@
|
||||
The configuration file config.yml contains two settings that influence the logging that AuthMe will perform.
|
||||
|
||||
#### Security.console.logConsole (true / false)
|
||||
If set to `true`, everything that AuthMe logs to the console will also be saved in authme.log. If a technical error occurs (called _Exception_ in Java), the full stacktrace is logged. This provides more technical details about the error, which are very interesting for us developers to know about.
|
||||
|
||||
#### settings.logLevel (INFO / FINE / DEBUG)
|
||||
We recommend `FINE`. This logs, additionally to the INFO ones, some finer details which are still relevant and interesting to keep in a log. Use `DEBUG` if you're interested in seeing a lot of information from AuthMe. This is typically only used when you're trying to find the cause of an issue with AuthMe.
|
||||
125
Dependency-Injection.md
Normal file
125
Dependency-Injection.md
Normal file
@ -0,0 +1,125 @@
|
||||
This page contains some details about the purpose of the `@Inject` annotations in AuthMe and how to use them.
|
||||
|
||||
- [Purpose](#purpose)
|
||||
- [Inversion of control](#inversion-of-control)
|
||||
- [Dependency injection](#dependency-injection)
|
||||
- [Injection methods](#injection-methods)
|
||||
- [Constructor injection](#constructor-injection)
|
||||
- [Field injection](#field-injection)
|
||||
- [@Inject gets singletons](#inject-gets-singletons)
|
||||
|
||||
# Purpose
|
||||
`@Inject` allows us to use inversion of control more easily.
|
||||
|
||||
## Inversion of control
|
||||
In a nutshell, inversion of control means that we _pass_ the services a class needs from the outside, instead of having the class instantiate or find (`getInstance()`) the service itself. This renders dependencies explicit (we are more aware of our service's dependencies), makes it easier to switch out a component in the future and facilitates unit testing.
|
||||
|
||||
### Example
|
||||
Consider the following class:
|
||||
```java
|
||||
public class MessageTask {
|
||||
|
||||
public void setTask(String name) {
|
||||
if (PlayerCache.getInstance().isAuthenticated(name) && LimboCache.getInstance().hasLimboPlayer(name)) {
|
||||
LimboCache.getInstance().getLimboPlayer(name).initMessageTask();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Applying inversion of control, the class could look as follows:
|
||||
```java
|
||||
public class MessageTask {
|
||||
|
||||
private final PlayerCache playerCache;
|
||||
private final LimboCache limboCache;
|
||||
|
||||
public MessageTask(PlayerCache playerCache, LimboCache limboCache) {
|
||||
this.playerCache = playerCache;
|
||||
this.limboCache = limboCache;
|
||||
}
|
||||
|
||||
public void setTask(String name) {
|
||||
if (playerCache.isAuthenticated(name) && limboCache.hasLimboPlayer(name)) {
|
||||
limboCache.getLimboPlayer(name).initMessageTask();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With the second version, we immediately see that `MessageTask` needs a `LimboCache` and `PlayerCache` instance. We can easily test the class by passing mock implementations, whereas in the first version we do not have the possibility to switch the implementation.
|
||||
|
||||
## Dependency injection
|
||||
### Without dependency injection
|
||||
One disadvantage with the "inversion of control" variant in the above code is that initializing the class becomes more difficult as we have to explicitly know about its dependencies (and in turn, of _their_ dependencies). Consider the following code:
|
||||
|
||||
```java
|
||||
private CommandHandler initializeCommandHandler(PermissionsManager permissionsManager, Messages messages,
|
||||
PasswordSecurity passwordSecurity, NewSetting settings) {
|
||||
HelpProvider helpProvider = new HelpProvider(permissionsManager, settings.getProperty(HELP_HEADER));
|
||||
Set<CommandDescription> baseCommands = CommandInitializer.buildCommands();
|
||||
CommandMapper mapper = new CommandMapper(baseCommands, permissionsManager);
|
||||
CommandService commandService = new CommandService(
|
||||
this, mapper, helpProvider, messages, passwordSecurity, permissionsManager, settings);
|
||||
return new CommandHandler(commandService);
|
||||
}
|
||||
```
|
||||
We want to instantiate a `CommandHandler`. We need to pass a `CommandService` to it, so we need to initialize this first. However, it requires a `CommandMapper`, a `HelpProvider`... and so forth. This forces us to deal with tons of classes (CommandService, CommandMapper, etc.) we do not care about directly—we just want to get a `CommandHandler`.
|
||||
|
||||
### Purpose of dependency injection
|
||||
Dependency injection allows us to avoid huge initialization blocks by _injecting_ dependencies for us. We can simply request a class from the injector:
|
||||
```java
|
||||
CommandHandler handler = injector.getSingleton(CommandHandler.class);
|
||||
```
|
||||
The injector will scan the CommandHandler class for its dependencies, instantiate them and pass them to the class _for us_. Basically, it does the big code chunk from above for us automatically. We need to help the injector a little bit by annotating the dependencies with `@Inject` in order to tell the injector what to inject.
|
||||
|
||||
# Injection methods
|
||||
Dependencies can be passed to a class in different ways. It is important to only use one form per class.
|
||||
|
||||
## Constructor injection
|
||||
A constructor can be annotated with `@Inject`. This tells the injector that the parameters of that constructor need to be injected. Consider the `MessageTask` class from the first example. We only need to add an annotation to enable constructor injection:
|
||||
|
||||
```java
|
||||
public class MessageTask {
|
||||
|
||||
private final PlayerCache playerCache;
|
||||
private final LimboCache limboCache;
|
||||
|
||||
@Inject
|
||||
MessageTask(PlayerCache playerCache, LimboCache limboCache) {
|
||||
this.playerCache = playerCache;
|
||||
this.limboCache = limboCache;
|
||||
}
|
||||
|
||||
public void setTask(String name) {
|
||||
if (playerCache.isAuthenticated(name) && limboCache.hasLimboPlayer(name)) {
|
||||
limboCache.getLimboPlayer(name).initMessageTask();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now a MessageTask singleton can be gotten via `injector.getSingleton(MessageTask.class)`. The injector will notice that `PlayerCache` and `LimboCache` are required and will pass them to the constructor.
|
||||
|
||||
## Field injection
|
||||
Alternatively, fields can be annotated with `@Inject`:
|
||||
|
||||
```java
|
||||
public class MessageTask {
|
||||
|
||||
@Inject
|
||||
private PlayerCache playerCache;
|
||||
@Inject
|
||||
private LimboCache limboCache;
|
||||
|
||||
public void setTask(String name) {
|
||||
if (playerCache.isAuthenticated(name) && limboCache.hasLimboPlayer(name)) {
|
||||
limboCache.getLimboPlayer(name).initMessageTask();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Again, the injector will see the annotations on the fields and will set the fields. The fields can be `private` or have any other visibility. Field injection requires a no-arg constructor to be present.
|
||||
|
||||
## @Inject gets singletons
|
||||
No matter if you use constructor injection or field injection, it's important to understand that singletons will be passed, i.e. the injector will always pass the same implementation of the class. For example, if you have `@Inject private LimboCache limboCache` in some class and another `@Inject private LimboCache limboCache` in another class, both fields will have the same `LimboCache` object.
|
||||
45
Development-Setup.md
Normal file
45
Development-Setup.md
Normal file
@ -0,0 +1,45 @@
|
||||
Some tips and recommendations for people who want to work on AuthMe.
|
||||
|
||||
# Maven
|
||||
If the `org.bukkit` classes are not available as a dependency, ensure that the Maven profile "spigot" is enabled. This adds the Spigot API as dependency to the project. Alternatively, you can enable the "bukkit" profile (be sure to disable "spigot" then). This allows us to easily verify that our code compiles against both APIs.
|
||||
|
||||
For local development, you can enable the profile "skipLongHashTests". This disables some of the hash algorithm tests and shaves off a substantial amount of time from the build time.
|
||||
|
||||
# IntelliJ
|
||||
- Make sure you are running idea**64**.exe if on a 64-bit operating system (faster).
|
||||
|
||||
- Maven: if asked to enable auto-import, select it. This will update your dependencies automatically when they are changed in the pom.xml
|
||||
|
||||
- If `@Inject` fields are marked with the "never declared" warning, go to Settings > search "unused declaration," select the Java one and press the button "Configure annotations." Add `@Inject` and `@InjectDelayed`.
|
||||
|
||||
- You can make issue numbers in commit messages clickable by going to Settings > search "issue navigation", add a new rule:
|
||||
```
|
||||
Issue ID: #(\d+)
|
||||
Issue link: https://github.com/Xephi/AuthMeReloaded/issues/$1
|
||||
```
|
||||
|
||||
- Do you get an error message "missing argLine" when trying to run unit tests? Go to settings > search "Running Tests" and uncheck "argLine"
|
||||
|
||||
### Checkstyle
|
||||
IntelliJ has a checkstyle plugin that nicely couples with our use of [Code Climate](https://codeclimate.com/github/AuthMe/AuthMeReloaded/issues). With the plugin you can perform the same validations in your IDE as is done on remotely on Code Climate.
|
||||
|
||||
- Ctrl+Shift+A, type "Plugins" and search for "Checkstyle". If it doesn't appear click on "Search repositories."
|
||||
- Install Checkstyle-IDEA
|
||||
- In File > Settings > Other Settings > Checkstyle, add the configuration file (.checkstyle.xml). Don't forget to check the "Active" checkbox.
|
||||
|
||||
After this, checkstyle will automatically run on your IDE and rule violations will be shown as warnings.
|
||||
|
||||
# Forking AuthMe
|
||||
- Please fork the [AuthMe/AuthMeReloaded](https://github.com/AuthMe/AuthMeReloaded) repo, NOT the one under Xephi's name. The AuthMe/AuthMeReloaded repo is sometimes hundreds of commits ahead.
|
||||
|
||||
- Tip: add the AuthMe repository to Git. Execute in console: `git remote add upstream https://github.com/AuthMe/AuthMeReloaded.git`. In IntelliJ use Ctrl+Shift+A > "fetch" and you will see the branches of your repository as well as of the AuthMe-Team.
|
||||
|
||||
- Do not commit _any_ changes to your master. Use it only to keep in sync with the upstream repo. This way you can always pull new changes from the parent repo into your local master without any conflicts. Then you can merge your local master with your custom branches to keep them up to date.
|
||||
- If you commit changes to your fork's master directly, you will generate a merge commit every time you pull new changes from AuthMe/AuthMeReloaded into your local master. This creates unnecessary noise in the Git history and generates ugly pull requests.
|
||||
|
||||
# Debugging AuthMe in IntelliJ
|
||||
See _[Run Configuration to Debug Bukkit/Minecraft Plugin in IntelliJ IDEA](http://stackoverflow.com/a/29945539)_ on StackOverflow.
|
||||
|
||||
If you get `ClassDefNotFoundError`, make sure you extract all dependencies into the JAR. Right-click the dependencies on the right and select "Extract Into Output Root." Then move them inside the JAR file.
|
||||
|
||||
|
||||
11
Home.md
11
Home.md
@ -1 +1,12 @@
|
||||
Welcome to the AuthMeReloaded wiki!
|
||||
|
||||
If you are using AuthMe on your server, the following pages might be of interest to you:
|
||||
- [AuthMe releases (Jenkins)](https://github.com/AuthMe-Team/AuthMeReloaded/wiki/AuthMe-Releases-(Jenkins)) – how to get the latest version of AuthMe
|
||||
- [Breaking changes](https://github.com/AuthMe-Team/AuthMeReloaded/wiki/Breaking-Changes)
|
||||
- [Permission nodes](https://github.com/AuthMe-Team/AuthMeReloaded/blob/master/docs/permission_nodes.md)
|
||||
- [Spawn handling](https://github.com/AuthMe-Team/AuthMeReloaded/wiki/Spawn-Handling) (how AuthMe teleports users)
|
||||
- ["please-verify" on issues](https://github.com/AuthMe-Team/AuthMeReloaded/wiki/'please-verify'-Label)
|
||||
|
||||
The remaining Wiki pages are aimed at developers.
|
||||
|
||||
|
||||
18
Hooking-into-AuthMe.md
Normal file
18
Hooking-into-AuthMe.md
Normal file
@ -0,0 +1,18 @@
|
||||
A technical description for plugin developers on how to interact with AuthMe.
|
||||
|
||||
### API
|
||||
We offer an API for performing actions and queries in AuthMe, see [NewAPI](http://ci.xephi.fr/job/AuthMeReloaded/javadoc/fr/xephi/authme/api/NewAPI.html). You can get the `NewAPI` object the following way:
|
||||
```java
|
||||
import fr.xephi.authme.api.NewAPI;
|
||||
// ...
|
||||
NewAPI authmeApi = NewAPI.getInstance();
|
||||
```
|
||||
The individual methods are described in the Javadoc (see link above).
|
||||
|
||||
### Events
|
||||
Before or after various actions, we throw an _Event_ you can listen to in your plugin. All AuthMe events extend the [CustomEvent class](http://ci.xephi.fr/job/AuthMeReloaded/javadoc/fr/xephi/authme/events/CustomEvent.html). You can see a list of all events and their hierarchy [here](http://ci.xephi.fr/job/AuthMeReloaded/javadoc/fr/xephi/authme/events/package-tree.html). All event classes are described with Javadoc.
|
||||
|
||||
Note that not all events can be canceled—only the ones extending Bukkit's `Cancellable` interface.
|
||||
|
||||
### Demo Plugin
|
||||
A functional plugin demonstrating AuthMe integration is hosted on the [ljacqu/AuthMe_demo_integration](https://github.com/ljacqu/AuthMe_integration_demo) repository.
|
||||
34
Name-Restrictions.md
Normal file
34
Name-Restrictions.md
Normal file
@ -0,0 +1,34 @@
|
||||
AuthMe supports restrictions and so-called _unrestrictions_ for usernames.
|
||||
|
||||
## Name Restrictions
|
||||
Names can be restricted to IP addresses or host names. An example in config.yml:
|
||||
```yaml
|
||||
# To activate the restricted user feature you need
|
||||
# to enable this option and configure the AllowedRestrictedUser field.
|
||||
AllowRestrictedUser: true
|
||||
# The restricted user feature will kick players listed below
|
||||
# if they don't match the defined IP address. Names are case-insensitive.
|
||||
AllowedRestrictedUser:
|
||||
- admin;127.0.0.1
|
||||
- admin;123.45.67.89
|
||||
- billy;34.56.78.90
|
||||
```
|
||||
|
||||
This means that someone may only join as `admin` if he has the IP address 127.0.0.1 or 123.45.67.89. Attempts to join as `admin` from any other IP address will be refused. This setting is case-insensitive, i.e. the restrictions also apply for `ADMIN`, `Admin`, etc.
|
||||
|
||||
To "disable" certain usernames, you can add entries with an impossible address, e.g. "player;8.8.8.8" to refuse anyone joining as `Player`.
|
||||
|
||||
## Name Unrestrictions
|
||||
Conversely, name unrestrictions define usernames that AuthMe will ignore entirely. Example for config.yml:
|
||||
|
||||
```yaml
|
||||
# Below you can list all account names that AuthMe will ignore
|
||||
# for registration or login. Configure it at your own risk!!
|
||||
# This option adds compatibility with BuildCraft and some other mods.
|
||||
# It is case-insensitive!
|
||||
UnrestrictedName:
|
||||
- npcplayer
|
||||
- othernpc
|
||||
```
|
||||
|
||||
This setting is also case-insensitive. If a player with such a name joins (e.g. `npcplayer`, or `NpcPlayer`), AuthMe won't ask the player to log in or register and won't block any commands or actions. This is typically a useful feature for plugins that add NPC players to the game.
|
||||
34
Plugins-hooking-into-AuthMe.md
Normal file
34
Plugins-hooking-into-AuthMe.md
Normal file
@ -0,0 +1,34 @@
|
||||
### Plugins with recent commits (< 1 year)
|
||||
Plugin | Source code
|
||||
----------- | ---------
|
||||
AuthMeBridge | [Github](https://github.com/CryLegend/AuthMeBridge/blob/master/authmebridge-authme/src/main/java/com/crylegend/authmebridge/AuthMeBridge.java)
|
||||
ChatGuard | [Github](https://github.com/DenAbr/ChatGuard/tree/master/src/ru/Den_Abr/ChatGuard/Integration)
|
||||
ChestShop | [Github](https://github.com/Acrobot/ChestShop-3/blob/master/src/main/java/com/Acrobot/ChestShop/Listeners/AuthMeChestShopListener.java)
|
||||
DungeonMaze | [Github](https://github.com/timvisee/DungeonMaze/tree/master/src/main/java/com/timvisee/dungeonmaze/plugin/authmereloaded)
|
||||
FactionChat | [Github](https://github.com/James137137/FactionChat/blob/master/src/main/java/nz/co/lolnet/james137137/FactionChat/API/AuthMeAPI.java)
|
||||
FastLogin | [Github](https://github.com/games647/FastLogin/blob/master/bukkit/src/main/java/com/github/games647/fastlogin/bukkit/hooks/AuthMeHook.java)
|
||||
ResourcePacksPlugins | [Github](https://github.com/Phoenix616/ResourcepacksPlugins/blob/master/bukkit/src/main/java/de/themoep/resourcepacksplugin/bukkit/listeners/AuthmeLoginListener.java)
|
||||
Scavenger | [Github](https://github.com/cnaude/Scavenger/blob/master/src/main/java/com/cnaude/scavenger/Scavenger.java)
|
||||
|
||||
### Further plugins
|
||||
Plugins with recent commits (< 1 year) that are very specific or that are lacking a description.
|
||||
|
||||
Plugin | Source code
|
||||
----------- | -----------
|
||||
CreativeLimiter | [Github](https://github.com/Shevchik/CreativeLimiter/blob/master/src/creativeLimiter/misc/JoinGamemodeChanger.java)
|
||||
Elementals | [Github](https://github.com/nicuch/Elementals/blob/master/src/ro/nicuch/elementals/hook/NCPHookListener.java)
|
||||
NoMult | [Github](https://github.com/Korvinius/NoMult/blob/master/src/net/wealth_mc/nomult/NoMultList.java)
|
||||
ProtocolSupportPremiumLogin | [Github](https://github.com/ProtocolSupport/ProtocolSupportPremiumLogin/blob/master/src/premiumlogin/plugins/AuthMeNewHook.java)
|
||||
RPGGame-Plugin | [Github](https://github.com/AngelAZO/RPGGame-Plugin/blob/master/src/com/minephoenix/legacy/PlayerEvents.java)
|
||||
SinkBans | [Github](https://github.com/Static-Interface/SinkBans)
|
||||
UniversalChat | [Github](https://github.com/Phosphorus15/UniversalChat)
|
||||
|
||||
### Abandoned plugins
|
||||
Plugins whose last commit was over a year ago.
|
||||
|
||||
Plugin | Source code
|
||||
--------- | ------------
|
||||
NewTrans | [Github](https://github.com/BAI1/NewTrans/blob/master/me/bai1/NewTrans/NewTrans.java)
|
||||
RealMotd | [Github](https://github.com/tomsik68/RealMotd/blob/master/src/sk/tomsik68/realmotd/RealMotd.java)
|
||||
WAddon | [Github](https://github.com/ShadowDevelopment/WAddon/tree/master/src/me/wiedzmin137/waddon/listener)
|
||||
WHeroesAddon | [Github](https://github.com/ShadowDevelopment/WHeroesAddon/blob/master/src/me/Wiedzmin137/wheroesaddon/addons/WEventListener.java)
|
||||
15
Registration.md
Normal file
15
Registration.md
Normal file
@ -0,0 +1,15 @@
|
||||
AuthMe supports different types of registration. You can configure the type of registration by changing the `type` setting under `registration` in your config.yml.
|
||||
|
||||
## Password Registration
|
||||
The default registration: the user provides the password he wants to use to `/register`. The account is registered with the given password.
|
||||
|
||||
You can disable passwords from being used in `unsafePasswords` and length restrictions can be configured with `minPasswordLength` and `passwordMaxLength` in config.yml.
|
||||
|
||||
**Example:**
|
||||
> Player "Bobby" uses `/register s3cret s3cret` -> AuthMe registers "Bobby" with password "s3cret"
|
||||
|
||||
## Email Registration
|
||||
The user provides his email address to `/register`. AuthMe will generate a password for the account and email it to the given email address.
|
||||
|
||||
## Two Factor Registration
|
||||
:warning: **Work in progress** -- allows users to register with an authenticator app, i.e. each time they log in they have to enter a number generated by the app.
|
||||
57
Spawn-Handling.md
Normal file
57
Spawn-Handling.md
Normal file
@ -0,0 +1,57 @@
|
||||
This page describes how teleportation is handled and configured in AuthMe.
|
||||
|
||||
## Settings
|
||||
The following settings have an influence on the spawn feature, listed by priority:
|
||||
|
||||
1. `settings.restrictions.noTeleport` — if set to true, AuthMe will _never_ teleport players
|
||||
1. `settings.restrictions.spawnPriority` — list of spawns to consider by priority (supported: authme, essentials, multiverse, default)
|
||||
1. `settings.restrictions.ForceSpawnLocOnJoin.enabled` — if set to true, players are teleported to spawn _after_ having logged in successfully
|
||||
1. `settings.restrictions.ForceSpawnLocOnJoin.worlds` — limits the above feature only to the given worlds (case-sensitive)
|
||||
1. `settings.restrictions.teleportUnAuthedToSpawn` — if set to true, teleports players to spawn when they join. Once they log in, they are teleported back to their original location
|
||||
|
||||
--
|
||||
Related: `settings.restrictions.SaveQuitLocation` must be true for the quit location to be saved in the database. If `false`, players are teleported back to the location in which they would have joined without changes from AuthMe.
|
||||
|
||||
## Spawn Priority
|
||||
Spawn priority is defined in `settings.restrictions.spawnPriority` (see above), i.e. this setting defines from where the spawn definition should be taken. Possible values:
|
||||
|
||||
- **authme** — Spawn points defined in spawn.yml (AuthMe folder). See below for details.
|
||||
- **essentials** — Spawn as defined in Essentials' spawn.yml. Only applicable if Essentials is loaded on the server.
|
||||
- **multiverse** — Gets the spawn point saved in Multiverse for the given world. Only possible if Multiverse is loaded and the world is a Multiverse handled world.
|
||||
- **default** — Spawn location of the world (vanilla Minecraft)
|
||||
|
||||
Example:
|
||||
```yaml
|
||||
spawnPriority: 'essentials,authme,default'
|
||||
```
|
||||
If Essentials is available, the spawn defined in Essentials is used. If not, the AuthMe spawn is used as second choice. If this also fails, the default is taken.
|
||||
|
||||
## AuthMe Spawn
|
||||
The AuthMe spawnpoint is defined in spawn.yml of the AuthMe plugin folder. Example:
|
||||
|
||||
```yaml
|
||||
spawn:
|
||||
world: world
|
||||
x: -171.77925533614896
|
||||
y: 99.0
|
||||
z: 171.8600493294933
|
||||
yaw: -180.43475
|
||||
pitch: 13.7999935
|
||||
firstspawn:
|
||||
world: world
|
||||
x: -167.00317045444243
|
||||
y: 98.0
|
||||
z: 142.33661923798473
|
||||
yaw: -342.2848
|
||||
pitch: 11.849992
|
||||
```
|
||||
|
||||
Players who have never played on the server before are teleported to the **firstspawn**; otherwise they are teleported to the regular spawnpoint as defined by the spawn priority. You can delete the `firstspawn` section to disable this feature.
|
||||
|
||||
## AuthMe Spawn Commands
|
||||
- `/authme spawn` teleports you to the AuthMe spawn point
|
||||
- `/authme setspawn` sets the AuthMe spawn point
|
||||
- `/authme firstspawn` teleports you to the AuthMe first spawn point
|
||||
- `/authme setfirstspawn` sets the AuthMe first spawn point
|
||||
|
||||
Permission nodes for the commands are listed on the [command list page](https://github.com/AuthMe-Team/AuthMeReloaded/blob/master/docs/commands.md).
|
||||
78
Tool-tasks.md
Normal file
78
Tool-tasks.md
Normal file
@ -0,0 +1,78 @@
|
||||
_Tool tasks_ are tasks that can be run from the AuthMe codebase for various purposes, e.g. to generate docs pages or to verify the completeness of translation files. All tool tasks are started from the same runner, the ToolsRunner, located under `test/tools/ToolsRunner.java`. Tip: you can save the run configuration for the ToolsRunner so that you can easily run a tool task at any time.
|
||||
|
||||
Once you start the ToolsRunner, a list of all available tools will be displayed. After entering the name the corresponding task will be run.
|
||||
|
||||
## Available tasks
|
||||
Cat | Name | Description
|
||||
------------ | ----------------------- | -----------
|
||||
:paperclip: | addJavaDocToMessageEnum | Adds a JavaDoc comment to each MessageKey entry with the according English message.
|
||||
:flashlight: | checkMessageUses | Finds message keys which aren't used anywhere
|
||||
:paperclip: | checkTestMocks | Checks that test classes' `@Mock` fields correspond to the tested class' `@Inject` fields.
|
||||
:green_book: | createCommandPage | Updates the docs/commands.md page.
|
||||
:green_book: | describeHashAlgos | Updates the docs/hash_algorithms.md page.
|
||||
:paperclip: | drawDependencyGraph | Generates AuthMe's dependency graph as .dot file - requires GraphWiz to render.
|
||||
:pencil2: | generateCommandsYml | Creates the commands.yml config file with default data.
|
||||
:pencil2: | generatePluginYml | Generates the plugin.yml with up-to-date command and permission info.
|
||||
:green_book: | updateConfigPage | Updates the docs/config.md page.
|
||||
:green_book: | updateDocs | Updates all files in the docs/ folder.
|
||||
:green_book: | updateTranslations | Updates the docs/translations.md page.
|
||||
:flashlight: | verifyHelpTranslations | Verifies all or a specific help translation file in resources/messages.
|
||||
:flashlight: | verifyMessages | Verifies all or a specific messages file in resources/messages.
|
||||
:green_book: | writePermissionsList | Updates the docs/permission_nodes.md page.
|
||||
|
||||
### Categories
|
||||
Icon | Category
|
||||
------------ | --------
|
||||
:green_book: | Docs/ page generation
|
||||
:flashlight: | Verification task
|
||||
:pencil2: | Project file update
|
||||
:paperclip: | Technical task
|
||||
|
||||
## Tag replacements
|
||||
Markdown pages in the docs/ folder are created based on a template file. This template file may contain tags which are replaced with data during the generation process. For example:
|
||||
```txt
|
||||
A total of {total} commands are available:
|
||||
|
||||
[#commands]
|
||||
- {name}[perm], requires {perm}[/perm]
|
||||
[/#commands]
|
||||
```
|
||||
|
||||
Three types of tags are available:
|
||||
- Replacement: `{total}`-like tags will be replaced with the value associated with "total"
|
||||
- Conditional: `[perm]...[/perm]`-like tags are conditional tags. The text inside of the tags is only considered if the value associated with "perm" is not empty (empty string / empty collection)
|
||||
- Repeating: tags like `[#commands]...[/#commands]` will make us iterate over all entries in "commands" and apply replacements to the text within
|
||||
|
||||
Values can be associated to tag names with a `TagValueHolder`. Example:
|
||||
```java
|
||||
List<Command> commands = Arrays.asList(
|
||||
new Command("/home", ""), new Command("/help", "permission.help"));
|
||||
|
||||
NestedTagValue commandsInfo = new NestedTagValue();
|
||||
for (Command command : commands) {
|
||||
TagValueHolder commandValues = TagValueHolder.create()
|
||||
.put("name", command.getName())
|
||||
.put("perm", command.getPermission());
|
||||
commandsInfo.add(commandValues);
|
||||
}
|
||||
|
||||
TagValueHolder tagValues = TagValueHolder.create()
|
||||
.put("total", commands.size())
|
||||
.put("commands", commandsInfo);
|
||||
|
||||
// Generate MD file
|
||||
FileIoUtils.generateFileFromTemplate("commands.tpl.md", "commands.md", tagValues);
|
||||
```
|
||||
|
||||
The generated file would look like the following:
|
||||
```md
|
||||
A total of 2 commands are available:
|
||||
|
||||
- /home
|
||||
- /help, requires permission.help
|
||||
```
|
||||
|
||||
The following predefined tags are at your disposal:
|
||||
- `{gen_date}`: generation date (i.e. current date)
|
||||
- `{gen_warning}`: comment warning not to edit the output file directly
|
||||
- `{gen_footer}`: info footer with a link to the repo and the generation date
|
||||
27
Translators.md
Normal file
27
Translators.md
Normal file
@ -0,0 +1,27 @@
|
||||
Language | Translators
|
||||
-------- | ------------
|
||||
bg | @[JunkyBulgaria](https://github.com/JunkyBulgaria) @[Krokit](https://github.com/Krokit)
|
||||
br | @[DeathrushW](https://github.com/DeathrushW) @[RoinujNosde](https://github.com/RoinujNosde) @[nathampa0909](https://github.com/nathampa0909) @[evernife](https://github.com/evernife)
|
||||
cz | @[koca2000](https://github.com/koca2000)
|
||||
de | @[Platinteufel](https://github.com/Platinteufel) @[EvilOlaf](https://github.com/EvilOlaf) @[irobin591](https://github.com/irobin591)
|
||||
en | —
|
||||
es | @[jeremy100](https://github.com/jeremy100)
|
||||
eu | galaipa on Bukkit Dev (see commit `2119523`)
|
||||
fi | ?
|
||||
fr | @[Twonox](https://github.com/Twonox)
|
||||
gl | ?
|
||||
hu | @[rErEaT](https://github.com/rErEaT)
|
||||
id | @[DNx5](https://github.com/DNx5)
|
||||
it | @[Maxetto](https://github.com/Maxetto)
|
||||
ko | @[wolfwork](https://github.com/wolfwork)
|
||||
lt | ?
|
||||
nl | @[timvisee](https://github.com/timvisee)
|
||||
pl | @[RikoDEV](https://github.com/RikoDEV)
|
||||
pt | @[ice41](https://github.com/ice41) @[rafael59r2](https://github.com/rafael59r2)
|
||||
ro | @[nicuch](https://github.com/nicuch)
|
||||
ru | @[DardBrinza](https://github.com/DardBrinza) @[DenPim](https://github.com/DenPim) @[Bodyash](https://github.com/Bodyash)
|
||||
sk | ?
|
||||
tr | @[smt287](https://github.com/smt287) @[Twonox](https://github.com/Twonox)
|
||||
uk | @[Kixot14](https://github.com/Kixot14) @[Bodyash](https://github.com/Bodyash)
|
||||
vn | @[tuanjr](https://github.com/tuanjr) kythuat on Bukkit dev
|
||||
zh* | @[lifehome](https://github.com/lifehome) @[i998979](https://github.com/i998979); zhhk/zhmc: @[tsangsiuki12](https://github.com/tsangsiuki12); zhcn: @[Playhi](https://github.com/Playhi)
|
||||
67
Unit-Testing.md
Normal file
67
Unit-Testing.md
Normal file
@ -0,0 +1,67 @@
|
||||
## Principles
|
||||
Unit tests are for testing a _unit_: a particular class' methods are tested (ideally) in isolation to ensure that the logic contained within the class corresponds to our expectations. In contrast, _integration tests_ verify that two or more components interact correctly.
|
||||
|
||||
Unit tests have no guaranteed order in which they are run – neither for the order of the methods within a class, nor for the order of the test classes themselves. Unit tests should _not_ rely on previous tests to be set up. This is typically the case if a test works fine while running all tests but fails when run in isolation.
|
||||
|
||||
Needless to say, things inside of the test/ folder may not be used anywhere outside. Testing is an isolated scope and the project must be able to be built without any of the test resources.
|
||||
|
||||
## Technologies
|
||||
We use JUnit, Hamcrest and Mockito for unit testing. **JUnit** is the general test framework to set up and run tests with; **Hamcrest** provides powerful matchers to test results with; **Mockito** enables us to _mock_ a class, i.e. to use the same interface of a class but to provide it with custom functionality to simulate a certain situation. This facilitates _unit_ testing: we only want to test one piece and imitate (mock) the rest.
|
||||
|
||||
## Conventions
|
||||
Tests for a particular class should be in a class with the class name and "Test" appended to it, e.g. to test the class `Player` create a class `PlayerTest`. JavaDoc is not required for tests that are (reasonably) self-explanatory. Start test methods with `should` and the expected behavior, e.g. `shouldKickPlayer()` if this is the expected end result.
|
||||
|
||||
While we don't use behavior-driven development, the typical format of the tests are still suitable and convenient for us. Each test is made up of three parts, namely `given`, `when` and `then`:
|
||||
|
||||
- `given` instantiates and defines the necessary objects and values to run the test (e.g. to produce the desired condition to test).
|
||||
- `when` is the command to test. Typically one line with a method call of the class that is being tested.
|
||||
- `then` verifies the result
|
||||
|
||||
The examples further below should illustrate how this works.
|
||||
|
||||
## Static injections and methods
|
||||
Mockito cannot mock all classes and methods – classes and methods may not be `final`, and methods may not be `static`.
|
||||
|
||||
Static methods are fine for lightweight utility classes (no state, no _heavy_ actions like performing I/O) and for the logger.
|
||||
|
||||
## Examples
|
||||
Note that the following is a made up test and doesn't correspond to any existing classes in AuthMe. Given the following method:
|
||||
```java
|
||||
public static boolean isLoggedIn(CommandSender sender) {
|
||||
if (sender == null || !(sender instanceof Player)) {
|
||||
return false;
|
||||
}
|
||||
return Status.LOGGED_IN.equals(((Player) sender).getStatus());
|
||||
}
|
||||
```
|
||||
You may want to test that the method returns `false` if the sender is not an instance of `Player`, e.g. if the instance is `Console`.
|
||||
```java
|
||||
@Test
|
||||
public void shouldReturnFalseForNonPlayerSender() {
|
||||
// given
|
||||
CommandSender sender = Mockito.mock(Console.class);
|
||||
|
||||
// when
|
||||
boolean result = Verifier.isLoggedIn(sender);
|
||||
|
||||
// then
|
||||
assertThat(result, equalTo(false));
|
||||
}
|
||||
```
|
||||
|
||||
Now we want to test that a player is considered logged in if it returns the correct `Status`. This example shows the power of Mockito: we don't need to instantiate an actual player, where we might encounter issues to set the status to the desired one (e.g. if there is no setter for that method).
|
||||
|
||||
```java
|
||||
@Test
|
||||
public void shouldReturnTrueForLoggedInPlayer() {
|
||||
// given
|
||||
Player player = Mockito.mock(Player.class);
|
||||
given(player.getStatus()).willReturn(Status.LOGGED_IN);
|
||||
|
||||
// when
|
||||
boolean result = Verifier.isLoggedIn(sender);
|
||||
|
||||
// then
|
||||
assertThat(result, equalTo(true));
|
||||
}
|
||||
```
|
||||
21
_Sidebar.md
Normal file
21
_Sidebar.md
Normal file
@ -0,0 +1,21 @@
|
||||
- [Home](Home)
|
||||
- For plugin users
|
||||
- [AuthMe releases (Jenkins)](AuthMe-Releases-(Jenkins))
|
||||
- [Breaking changes](Breaking-Changes)
|
||||
- [Spawn handling](Spawn-Handling)
|
||||
- [Name restrictions](Name-Restrictions)
|
||||
- [Registration](Registration)
|
||||
- [Logging](Configuring-logging)
|
||||
- [Translators](Translators)
|
||||
- [5.2 changelog](5.2-Changelog)
|
||||
- For developers using AuthMe
|
||||
- [Hooking into AuthMe](Hooking-into-AuthMe)
|
||||
- [Plugins hooking into AuthMe](Plugins-hooking-into-AuthMe)
|
||||
- For developers
|
||||
- [Coding styleguide](AuthMe-Coding-Styleguide)
|
||||
- [Build history](Build-History)
|
||||
- [Command handling](Command-Handling)
|
||||
- [Dependency injection](Dependency-Injection)
|
||||
- [Development setup](Development-Setup)
|
||||
- [Tool tasks](Tool-tasks)
|
||||
- [Unit testing](Unit-Testing)
|
||||
Loading…
Reference in New Issue
Block a user