diff --git a/README.md b/README.md index a0c05b6..6c10dbf 100644 --- a/README.md +++ b/README.md @@ -224,7 +224,7 @@ To turn it off, any one of these is enough: - `TRACE_USAGE_REPORTING=off` in the environment — the switch every trace client honours, checked before Parpt's own setting - `DO_NOT_TRACK=1` in the environment, per [consoledonottrack.com](https://consoledonottrack.com) -Every switch fails closed. `usage-reporting.enabled` defaults to `true` when it is not set at all, and otherwise keeps reporting on only when it is `true`, `on`, `yes` or `1`; `false`, `off`, `no`, `0`, a typo or a blank value (`USAGE_REPORTING_ENABLED=` set empty) turn it off. `TRACE_USAGE_REPORTING` set to anything but blank, `true`, `on`, `yes` or `1` turns reporting off, and so does `DO_NOT_TRACK` set to anything but blank, `0`, `false`, `off` or `no`. +Every switch fails closed. `usage-reporting.enabled` defaults to `true` when it is not set at all, and otherwise keeps reporting on only when it is `true`, `on`, `yes` or `1`; `false`, `off`, `no`, `0`, a typo or a blank value (`USAGE_REPORTING_ENABLED=` set empty) turn it off. `TRACE_USAGE_REPORTING` set to anything but blank, `true`, `on`, `yes` or `1` turns reporting off, and so does `DO_NOT_TRACK` set to anything but blank, `0`, `false`, `off` or `no`. Other spellings count as off too: `usage_reporting.enable=false`, `usage-reporting.disabled=true`, `usage-reporting=false` or `USAGE_REPORTING=off` (in an `application.yaml`, as `-D` or in the environment) turn reporting off even though Spring does not bind them to `usage-reporting.enabled`. The key under `usage-reporting.key` in `application.yaml` is the write key issued to Parpt; it can only add usage events and is not secret. diff --git a/src/main/java/com/preponderous/parpt/trace/NearMissOptOut.java b/src/main/java/com/preponderous/parpt/trace/NearMissOptOut.java new file mode 100644 index 0000000..a163554 --- /dev/null +++ b/src/main/java/com/preponderous/parpt/trace/NearMissOptOut.java @@ -0,0 +1,77 @@ +package com.preponderous.parpt.trace; + +import org.springframework.boot.context.properties.source.ConfigurationProperty; +import org.springframework.boot.context.properties.source.ConfigurationPropertyName; +import org.springframework.boot.context.properties.source.ConfigurationPropertySource; +import org.springframework.boot.context.properties.source.ConfigurationPropertySources; +import org.springframework.boot.context.properties.source.IterableConfigurationPropertySource; +import org.springframework.core.env.ConfigurableEnvironment; +import org.springframework.core.env.Environment; + +import java.util.Locale; + +/** + * Finds an attempt to turn usage reporting off that is not written as the real switch, + * {@code usage-reporting.enabled}. Spring binds only that name (and its relaxed forms, such as + * {@code USAGE_REPORTING_ENABLED}), so anything else used to be ignored and reporting stayed on. An operator + * who wrote any of these did not ask for reporting, so each counts as off: + * + * {@code TRACE_USAGE_REPORTING} is left to the client, which reads it itself. + */ +final class NearMissOptOut { + + private NearMissOptOut() { + } + + /** The near-miss property that turns reporting off, or null when there is none. */ + static String find(Environment environment, String realSwitch) { + if (!(environment instanceof ConfigurableEnvironment)) { + return null; + } + ConfigurationPropertyName switchName = ConfigurationPropertyName.of(realSwitch); + for (ConfigurationPropertySource source + : ConfigurationPropertySources.from(((ConfigurableEnvironment) environment).getPropertySources())) { + if (!(source instanceof IterableConfigurationPropertySource)) { + continue; + } + for (ConfigurationPropertyName name : (IterableConfigurationPropertySource) source) { + if (name.equals(switchName)) { + continue; // the switch itself, which Spring resolves + } + String key = normalise(name.toString()); + if (!key.contains("usagereport") || key.equals("traceusagereporting")) { + continue; + } + ConfigurationProperty property = source.getConfigurationProperty(name); + Object value = property == null ? null : property.getValue(); + if (isOptOut(key, value)) { + return name.toString(); + } + } + } + return null; + } + + static boolean isOptOut(String normalisedKey, Object value) { + if (normalisedKey.contains("disabl")) { + return TraceClient.allowsReporting(value); + } + if (normalisedKey.contains("enabl") || normalisedKey.endsWith("usagereporting")) { + return !TraceClient.allowsReporting(value); + } + return false; + } + + /** The key in lower case with everything but letters and digits dropped. */ + static String normalise(String key) { + return key.toLowerCase(Locale.ROOT).replaceAll("[^a-z0-9]", ""); + } +} diff --git a/src/main/java/com/preponderous/parpt/trace/UsageReporter.java b/src/main/java/com/preponderous/parpt/trace/UsageReporter.java index 5a489f3..2697b2e 100644 --- a/src/main/java/com/preponderous/parpt/trace/UsageReporter.java +++ b/src/main/java/com/preponderous/parpt/trace/UsageReporter.java @@ -7,6 +7,7 @@ import org.slf4j.LoggerFactory; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.beans.factory.annotation.Value; +import org.springframework.core.env.Environment; import org.springframework.stereotype.Component; import java.io.File; @@ -53,6 +54,8 @@ public class UsageReporter { static final String UNKNOWN_VERSION = "unknown"; /** The reason given when the endpoint, application name or version could not build a client. */ static final String INVALID_CONFIGURATION = "invalid usage-reporting configuration"; + /** The program's own switch, as Spring binds it. */ + static final String SWITCH = "usage-reporting.enabled"; private final TraceClient client; private final boolean invalidConfiguration; @@ -62,8 +65,22 @@ public class UsageReporter { public UsageReporter( @Value("${usage-reporting.enabled:true}") String enabled, @Value("${usage-reporting.endpoint:https://trace.danielstephenson.dev}") String endpoint, - @Value("${usage-reporting.key:}") String key) { - this(enabled, endpoint, key, resolveVersion(), defaultNoticeMarker()); + @Value("${usage-reporting.key:}") String key, + Environment environment) { + this(switchOrNearMissOptOut(enabled, environment), endpoint, key, resolveVersion(), defaultNoticeMarker()); + } + + /** + * The switch as Spring resolved it, or "false" when an opt-out is written under another name + * (see {@link NearMissOptOut}), which Spring would not bind to the switch at all. + */ + static String switchOrNearMissOptOut(String enabled, Environment environment) { + String nearMiss = NearMissOptOut.find(environment, SWITCH); + if (nearMiss != null) { + log.debug("Usage reporting is off: {} is read as an opt-out.", nearMiss); + return "false"; + } + return enabled; } UsageReporter(String enabled, String endpoint, String key, String version, Path noticeMarker) { diff --git a/src/test/java/com/preponderous/parpt/trace/NearMissOptOutTest.java b/src/test/java/com/preponderous/parpt/trace/NearMissOptOutTest.java new file mode 100644 index 0000000..50d8857 --- /dev/null +++ b/src/test/java/com/preponderous/parpt/trace/NearMissOptOutTest.java @@ -0,0 +1,106 @@ +package com.preponderous.parpt.trace; + +import org.junit.jupiter.api.Test; +import org.springframework.core.env.MapPropertySource; +import org.springframework.core.env.StandardEnvironment; +import org.springframework.core.env.SystemEnvironmentPropertySource; + +import java.util.LinkedHashMap; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; + +/** + * An opt-out written under a name Spring does not bind to {@value UsageReporter#SWITCH} used to be + * ignored, and reporting stayed on. + */ +class NearMissOptOutTest { + + /** An environment holding only the shipped defaults plus the given properties. */ + private static StandardEnvironment environment(Map file, Map env) { + StandardEnvironment environment = new StandardEnvironment(); + environment.getPropertySources().remove(StandardEnvironment.SYSTEM_PROPERTIES_PROPERTY_SOURCE_NAME); + environment.getPropertySources().remove(StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME); + environment.getPropertySources().addLast(new SystemEnvironmentPropertySource("env", env)); + environment.getPropertySources().addLast(new MapPropertySource("file", file)); + environment.getPropertySources().addLast(new MapPropertySource("defaults", + Map.of(UsageReporter.SWITCH, "true", "usage-reporting.endpoint", "http://127.0.0.1:9"))); + return environment; + } + + private static Map one(String key, Object value) { + Map map = new LinkedHashMap<>(); + map.put(key, value); + return map; + } + + @Test + void anOptOutWrittenUnderANearMissNameIsAnOptOut() { + Object[][] fileNearMisses = { + {"usage-reporting.enable", false}, + {"usage.reporting.enabled", "off"}, + {"usage_reporting.enable", false}, + {"usage_reporting.disabled", true}, + {"usage_reporting.disable", "yes"}, + {"usage_reporting", false}, + {"usage_reporting", "no"}, + }; + for (Object[] nearMiss : fileNearMisses) { + StandardEnvironment environment = environment(one((String) nearMiss[0], nearMiss[1]), Map.of()); + assertNotNull(NearMissOptOut.find(environment, UsageReporter.SWITCH), nearMiss[0] + "=" + nearMiss[1]); + assertEquals("false", UsageReporter.switchOrNearMissOptOut("true", environment), nearMiss[0] + "=" + nearMiss[1]); + } + String[][] envNearMisses = { + {"USAGE_REPORTING_DISABLED", "true"}, + {"USAGE_REPORTING_ENABLE", "false"}, + {"USAGE_REPORTING", "off"}, + }; + for (String[] nearMiss : envNearMisses) { + StandardEnvironment environment = environment(Map.of(), one(nearMiss[0], nearMiss[1])); + assertNotNull(NearMissOptOut.find(environment, UsageReporter.SWITCH), nearMiss[0] + "=" + nearMiss[1]); + } + } + + @Test + void nearMissNamesThatSayOnAreNotAnOptOut() { + Object[][] onSettings = { + {"usage_reporting.enable", true}, + {"usage_reporting.disabled", false}, + {"usageReporting", "on"}, + {"usage-reporting.endpoint", "http://127.0.0.1:9"}, + {"management.endpoints.enabled", false}, + }; + for (Object[] on : onSettings) { + StandardEnvironment environment = environment(one((String) on[0], on[1]), Map.of()); + assertNull(NearMissOptOut.find(environment, UsageReporter.SWITCH), on[0] + "=" + on[1]); + assertEquals("true", UsageReporter.switchOrNearMissOptOut("true", environment), on[0] + "=" + on[1]); + } + // The real switch is left to Spring, and the client reads TRACE_USAGE_REPORTING itself + // (a blank one, as docker-compose passes through, is not an opt-out). + assertNull(NearMissOptOut.find(environment(one(UsageReporter.SWITCH, "true"), + one("USAGE_REPORTING_ENABLED", "true")), UsageReporter.SWITCH)); + assertNull(NearMissOptOut.find(environment(Map.of(), one("TRACE_USAGE_REPORTING", "")), UsageReporter.SWITCH)); + assertNull(NearMissOptOut.find(environment(Map.of(), Map.of()), UsageReporter.SWITCH)); + } + + /** Spellings Spring binds to the switch itself are left to Spring, which reads them as the switch. */ + @Test + void spellingsSpringBindsAreReadAsTheSwitch() { + for (String spelling : new String[] {"usageReporting.enabled", "Usage_Reporting.Enabled"}) { + StandardEnvironment environment = environment(one(spelling, "false"), Map.of()); + assertNull(NearMissOptOut.find(environment, UsageReporter.SWITCH), spelling); + org.springframework.boot.context.properties.source.ConfigurationPropertySources.attach(environment); + assertEquals("false", environment.getProperty(UsageReporter.SWITCH), spelling); + } + } + + @Test + void theRealSwitchIsStillReadAsBefore() { + StandardEnvironment environment = environment(Map.of(), Map.of()); + assertEquals("false", UsageReporter.switchOrNearMissOptOut("false", environment)); + assertEquals("off", UsageReporter.switchOrNearMissOptOut("off", environment)); + assertEquals("true", UsageReporter.switchOrNearMissOptOut("true", environment)); + } +}