Skip to content

2.0.0

Choose a tag to compare

View all tags
@dmccoystephenson dmccoystephenson released this 19 Sep 15:52
v2.0.0
5c29157
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

2.0.0

Herald 2.0.0 hardens email delivery, checks the whole configuration at startup instead of failing on the first player join, adds usage reporting, and lets you customise the email subject and body. A server upgraded from 1.0.0 keeps its config.yml and its Discord notifications as they are. Email keeps working as long as your SMTP relay supports STARTTLS (when smtp.use-tls is true) and presents a certificate that matches smtp.server; if either is not the case, sends that used to succeed will start failing after the upgrade and need a one-line config change (see upgrade notes). On first start Herald also adds a usage-reporting block to config.yml, creates plugins/trace/config.yml, and sends one small event (plugin name and version) to the author's trace server unless you turn that off.

Changes

Email

  • smtp.use-tls: true now requires STARTTLS: a relay that cannot upgrade the connection fails the send instead of silently falling back to plaintext. The SMTP session now has connect, read and write timeouts, so an unreachable relay no longer parks the sending task forever (#44)
  • New smtp.implicit-tls for SMTPS relays (conventionally port 465). It is an alternative to smtp.use-tls, not an addition; setting both is reported at startup and email is skipped, and a port/mode mismatch on 465 or 587 is warned about (#47)
  • The relay's certificate is now checked against smtp.server. New smtp.verify-server-identity (default true) opts out, with a startup warning explaining what that costs (#49)
  • New email.enabled toggle (default true) to switch email off without clearing the SMTP settings (#33)
  • New email.subject and email.body templates supporting {player}, {server} and {time}; the default body now names the server instead of "the server" (#30, #15)
  • Startup warns when smtp.username is set but no encryption mode is on, since credentials would go over the wire in the clear (#29, #44)

Discord

  • A webhook message that Discord rate-limits is waited out (up to 10 s, as Discord's Retry-After asks) and retried once, with a warning in the log (#40)
  • discord.webhook-url is validated at startup (must be an absolute http/https URL) without the token being echoed into the log; blank discord.join-messages entries and templates that could exceed Discord's 2000-character limit once filled are reported at startup by position (#29, #33, #37)
  • Failed webhook calls include Discord's error body (invalid token, unknown webhook, etc.) in the logged failure (#21)

Startup checks and logging

  • Every configuration problem is reported at startup, naming the config key, rather than surfacing one per join; email now needs email.sender set and every address parseable before it is enabled, and warns when nothing is configured at all (#21, #29)
  • Notifier failures are logged with their cause and stack trace, and channels are named "Discord" and "email" in the log instead of by class name (#21, #30)
  • server-name is read once at enable rather than on every join, is trimmed, and a whitespace-only value falls back to "Minecraft" (#15, #37)

Usage reporting

  • On enable, Herald sends a startup event (plugin name and version, nothing about players or the server) to https://trace.danielstephenson.dev, off the main thread and dropped silently if unreachable. Turn it off with usage-reporting.enabled: false in Herald's config.yml, for every trace-reporting plugin with enabled: false in plugins/trace/config.yml, or for the whole process with TRACE_USAGE_REPORTING=off or DO_NOT_TRACK=1. The console states whether reporting is on at every start (#50, #53)

Distribution

  • A rolling prerelease of main is published as the dev release and can be installed with /dpm get herald --experimental; the release workflow no longer attaches a second, unverified jar to automated releases (#43, #46, #52)

Upgrade notes

  • If your relay does not support STARTTLS and you relied on 1.0.0 falling back to plaintext, email will now fail. Set smtp.use-tls: false (Herald will warn if credentials then go unencrypted) or move to a relay that supports STARTTLS.
  • If your relay's certificate does not name the host in smtp.server (reached by IP address, or a self-signed certificate), email will now fail with a certificate error. Either set smtp.server to the name on the certificate or set smtp.verify-server-identity: false.
  • If you use an SMTPS relay on port 465, set smtp.implicit-tls: true and smtp.use-tls: false; the old configuration on that port fails with a protocol error.
  • If you do not want usage reporting, set usage-reporting.enabled: false in plugins/Herald/config.yml after the first start (Herald writes the block for you), or set enabled: false in plugins/trace/config.yml to cover every plugin that reports to trace.
  • If you have your own class implementing com.dansplugins.herald.Notifier, it must now implement getDisplayName().

Version

1.0.0 → 2.0.0 — MAJOR. Mechanical floor from comparing the two jars: MINOR.
Judgment: Two email changes alter what an unchanged 1.0.0 config.yml does, which the jar comparison cannot see: smtp.use-tls: true now requires STARTTLS instead of attempting it and falling back to plaintext (#44), and the SMTP server's certificate is now checked against smtp.server by default (#49). A server whose relay lacks STARTTLS or presents a certificate for another name sent mail under 1.0.0 and will fail every send after upgrading, with no key edited. The Notifier interface also gained an abstract method, breaking any outside implementor, and usage reporting is on by default and writes new files, which is minor on its own but worth calling out.

  • minor: default config key added: email.body
  • minor: default config key added: email.enabled
  • minor: default config key added: email.subject
  • minor: default config key added: smtp.implicit-tls
  • minor: default config key added: smtp.verify-server-identity
  • minor: default config key added: usage-reporting.enabled
  • minor: default config key added: usage-reporting.endpoint
  • minor: default config key added: usage-reporting.key
  • info: public class added: com.dansplugins.herald.trace.TraceClient
  • info: public class added: com.dansplugins.herald.trace.TraceClient$Builder
  • info: com.dansplugins.herald.DiscordNotifier: added public com.dansplugins.herald.DiscordNotifier(java.lang.String, java.util.List<java.lang.String>, java.util.logging.Logger);
  • info: com.dansplugins.herald.DiscordNotifier: added public java.lang.String getDisplayName();
  • info: com.dansplugins.herald.DiscordNotifier: added public static java.util.List<java.lang.String> validateConfiguration(java.lang.String);
  • info: com.dansplugins.herald.DiscordNotifier: added public static java.util.List<java.lang.String> validateConfiguration(java.lang.String, java.util.List<java.lang.String>);
  • info: com.dansplugins.herald.DiscordNotifier: added public static java.util.List<java.lang.String> validateConfiguration(java.lang.String, java.util.List<java.lang.String>, java.lang.String);
  • info: com.dansplugins.herald.EmailNotifier: added public com.dansplugins.herald.EmailNotifier(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, boolean, boolean, boolean, java.util.List<java.lang.String>, java.lang.String, java.lang.String);
  • info: com.dansplugins.herald.EmailNotifier: added public com.dansplugins.herald.EmailNotifier(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, boolean, boolean, java.util.List<java.lang.String>, java.lang.String, java.lang.String);
  • info: com.dansplugins.herald.EmailNotifier: added public com.dansplugins.herald.EmailNotifier(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String, boolean, java.util.List<java.lang.String>, java.lang.String, java.lang.String);
  • info: com.dansplugins.herald.EmailNotifier: added public java.lang.String getDisplayName();
  • info: com.dansplugins.herald.EmailNotifier: added public static java.lang.String describeCredentialExposure(java.lang.String, boolean, boolean);
  • info: com.dansplugins.herald.EmailNotifier: added public static java.lang.String describePortTlsMismatch(int, boolean);
  • info: com.dansplugins.herald.EmailNotifier: added public static java.lang.String describeTlsModeConflict(boolean, boolean);
  • info: com.dansplugins.herald.EmailNotifier: added public static java.lang.String describeUnverifiedServerIdentity(boolean, boolean, boolean);
  • info: com.dansplugins.herald.EmailNotifier: added public static java.util.List<java.lang.String> validateConfiguration(java.util.List<java.lang.String>, java.lang.String, int, java.lang.String);
  • info: com.dansplugins.herald.Notifier: added public abstract java.lang.String getDisplayName();

Verification

Booted twice on a real Spigot server before publication — boot gate run (8 assertions passed). This release carries the exact jar that was verified.

Install with Dan's Plugin Manager: /dpm get <plugin>. How stable releases are made: Release channels.

drafted by Claude on behalf of Daniel Stephenson

Assets 3
Loading