Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
77 changes: 77 additions & 0 deletions src/main/java/com/preponderous/parpt/trace/NearMissOptOut.java
Original file line number Diff line number Diff line change
@@ -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:
* <ul>
* <li>a property that spells "enabled" another way under any spelling of "usage reporting"
* ({@code usage_reporting.enable}, {@code usageReporting.Enabled}, ...) whose value is not
* clearly on ({@link TraceClient#allowsReporting(Object)});</li>
* <li>one that spells "disabled" ({@code usage-reporting.disabled}, {@code USAGE_REPORTING_DISABLE},
* ...) whose value is on;</li>
* <li>a value given to "usage reporting" itself ({@code usage-reporting=false},
* {@code USAGE_REPORTING=off}, ...) that is not clearly on.</li>
* </ul>
* {@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]", "");
}
}
21 changes: 19 additions & 2 deletions src/main/java/com/preponderous/parpt/trace/UsageReporter.java
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand All @@ -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) {
Expand Down
106 changes: 106 additions & 0 deletions src/test/java/com/preponderous/parpt/trace/NearMissOptOutTest.java
Original file line number Diff line number Diff line change
@@ -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<String, Object> file, Map<String, Object> 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.<String, Object>of(UsageReporter.SWITCH, "true", "usage-reporting.endpoint", "http://127.0.0.1:9")));
return environment;
}

private static Map<String, Object> one(String key, Object value) {
Map<String, Object> 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));
}
}
Loading