Restrict environment names to a strict identifier

Names are trimmed, then must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$.
Anything else is unspecified and never rewritten.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: ejsmith

.agents/skills/exceptionless-java/SKILL.md

@@ -34,8 +34,8 @@ Always recommend importing `com.exceptionless:exceptionless-bom` to align versio
   appender to `log4j2.xml`; without `apiKey` it uses the starter's client.
 - Deployment environment: `config.environment("production")` is the default, `builder.setEnvironment("staging")`
   overrides it per event. Sent as the root `environment` property, separate from `data.@environment`.
-  Names are trimmed (casing kept); empty, over 64 characters or with control characters are
-  unspecified. An invalid non-null per-event name (e.g. `"  "`) sends the event without an environment
+  Names are trimmed (casing kept), then must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`; anything
+  else (`Staging West`, `prod/eu`, `produção`, empty, over 64 characters) is unspecified and never rewritten. An invalid non-null per-event name (e.g. `"  "`) sends the event without an environment
   instead of the default; `setEnvironment(null)` is no override and clears an earlier call, so the default applies. Code beats `EXCEPTIONLESS_ENVIRONMENT`, `exceptionless.environment` and
   `exceptionless.properties`; the Spring starter's only active profile is the last fallback.
 - `serverUrl(...)` also sets the config and heartbeat URLs; override those after it.

README.md

@@ -208,10 +208,11 @@ property or the `EXCEPTIONLESS_ENVIRONMENT` environment variable (or `exceptionl
 Spring Boot). A value set in code takes precedence; external configuration applies only when code has
 not set one. The Spring Boot starter uses the active profile only when no environment is configured
 and exactly one profile is active; a configured empty or invalid value leaves events unspecified
-instead. Names are trimmed and limited to 64 characters, preserving the supplied casing. The server
+instead. Names are trimmed, then must match `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`: ASCII letters, digits,
+`.`, `_` and `-`, starting with a letter or digit, at most 64 characters. Casing is preserved and
+names are never rewritten, so `Staging West`, `prod/eu` or `produção` are invalid. The server
 filters case-insensitively and normalizes aggregation keys. Missing or invalid names remain
-unspecified, and an invalid per-event name (non-null but empty, too long or with control characters)
-does not fall back to the configured default; pass `null` to `setEnvironment` to use the default. The
+unspecified, and an invalid non-null per-event name does not fall back to the configured default; pass `null` to `setEnvironment` to use the default. The
 top-level event `environment` is separate from machine diagnostics in `data.@environment`; stacks and
 fixed versions remain shared across environments. Older self hosted servers ignore the property, so
 upgrade the server first.

exceptionless-core/src/main/java/com/exceptionless/EventBuilder.java

@@ -56,10 +56,11 @@ public ContextData getContextData() {
 
   /**
    * Overrides the deployment environment for this event, instead of the configured default. The
-   * name is trimmed and keeps its casing. A name that is not valid (empty or white space, longer
-   * than 64 characters or with control characters) is still an override: the event is sent without
-   * an environment and does not fall back to the default. Null means no override: it clears any
-   * earlier call on this builder, and the configured default applies.
+   * name is trimmed and keeps its casing, then must match {@code
+   * ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$}. A name that is not valid (such as {@code "Staging West"} or
+   * an empty one) is still an override: the event is sent without an environment and does not fall
+   * back to the default. Null means no override: it clears any earlier call on this builder, and
+   * the configured default applies.
    */
   public EventBuilder setEnvironment(@Nullable String environment) {
     event.setEnvironment(environment);

exceptionless-core/src/main/java/com/exceptionless/ExceptionlessConfiguration.java

@@ -421,9 +421,10 @@ public boolean isEnvironmentConfigured() {
    * over {@code exceptionless.properties}, system properties and environment variables, whichever
    * is read last.
    *
-   * <p>The name is trimmed and keeps its casing. Empty names, names longer than 64 characters and
-   * names with control characters leave events without an environment (and still win over external
-   * configuration). Pass null to forget a value set here.
+   * <p>The name is trimmed and keeps its casing, then must match {@code
+   * ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$}. Any other name leaves events without an environment (and
+   * still wins over external configuration); names are never rewritten. Pass null to forget a value
+   * set here.
    */
   public ExceptionlessConfiguration environment(@Nullable String environment) {
     synchronized (environmentLock) {

exceptionless-core/src/main/java/com/exceptionless/internal/DeploymentEnvironment.java

@@ -1,21 +1,22 @@
 package com.exceptionless.internal;
 
+import java.util.regex.Pattern;
 import org.jspecify.annotations.Nullable;
 
 /**
- * Normalizes deployment environment names the way the server does, so the client never sends a
- * value the server would discard.
+ * Validates deployment environment names the way the server does, so the client never sends a value
+ * the server would discard.
  */
 public final class DeploymentEnvironment {
-  /** The longest name the server accepts. */
-  public static final int MAX_LENGTH = 64;
+  /** ASCII letters, digits, {@code .}, {@code _} and {@code -}; starts with a letter or digit. */
+  private static final Pattern VALID_NAME = Pattern.compile("^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$");
 
   private DeploymentEnvironment() {}
 
   /**
-   * Trims the name and returns it with its casing preserved, or null when the server would treat it
-   * as unspecified: empty, longer than {@value #MAX_LENGTH} characters or containing a control
-   * character.
+   * Trims the name and returns it with its casing preserved, or null when it is not a valid
+   * deployment environment name: ASCII letters, digits, {@code .}, {@code _} and {@code -},
+   * starting with a letter or digit, at most 64 characters. Names are never rewritten.
    */
   public static @Nullable String normalize(@Nullable String value) {
     if (value == null) {
@@ -29,21 +30,13 @@ private DeploymentEnvironment() {}
     while (end > start && isTrimmable(value.charAt(end - 1))) {
       end--;
     }
-    if (start == end || end - start > MAX_LENGTH) {
-      return null;
-    }
-    for (int i = start; i < end; i++) {
-      if (Character.isISOControl(value.charAt(i))) {
-        return null;
-      }
-    }
-    return value.substring(start, end);
+    String name = value.substring(start, end);
+    return VALID_NAME.matcher(name).matches() ? name : null;
   }
 
   /**
-   * Whether the server's trim removes the character: white space plus the Unicode space, line and
-   * paragraph separators. This is wider than {@link String#strip()}, which keeps non-breaking
-   * spaces.
+   * Whether the trim removes the character: white space plus the Unicode space, line and paragraph
+   * separators. This is wider than {@link String#strip()}, which keeps non-breaking spaces.
    */
   private static boolean isTrimmable(char c) {
     if ((c >= '\t' && c <= '\r') || c == ' ' || c == '\u0085') {

exceptionless-core/src/main/java/com/exceptionless/models/Event.java

@@ -41,9 +41,9 @@ public final class Event implements JsonSerializable {
   }
 
   /**
-   * Sets the deployment environment. The name is trimmed and keeps its casing. Empty names, names
-   * longer than 64 characters and names with control characters are not valid and clear the
-   * environment, so the event is sent without one.
+   * Sets the deployment environment. The name is trimmed and keeps its casing, then must match
+   * {@code ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$}. Any other name is not valid and clears the
+   * environment, so the event is sent without one; names are never rewritten.
    */
   public void setEnvironment(@Nullable String environment) {
     this.environment = DeploymentEnvironment.normalize(environment);

exceptionless-core/src/test/java/com/exceptionless/EventEnvironmentTest.java

@@ -151,6 +151,20 @@ void tooLongOverrideSendsTheEventUnspecifiedInsteadOfTheDefault() {
         .containsExactlyInAnyOrder(null, "x".repeat(64));
   }
 
+  @Test
+  void overrideOutsideTheNamingRuleSendsTheEventUnspecifiedInsteadOfTheDefault() {
+    config.environment("production");
+
+    client.createLog("space").setEnvironment("Staging West").submit();
+    client.createLog("slash").setEnvironment("prod/eu").submit();
+    client.createLog("unicode").setEnvironment("produ\u00e7\u00e3o").submit();
+    client.createLog("ok").setEnvironment("Staging-EU").submit();
+
+    assertThat(sent())
+        .extracting(e -> e.get("environment"))
+        .containsExactlyInAnyOrder(null, null, null, "Staging-EU");
+  }
+
   @Test
   void invalidDefaultSendsEventsUnspecified() {
     config.environment("x".repeat(65));
@@ -252,5 +266,9 @@ void eventSetterNormalizes() {
     assertThat(event.getEnvironment()).isEqualTo("Production");
     event.setEnvironment("x".repeat(65));
     assertThat(event.getEnvironment()).isNull();
+    event.setEnvironment("Staging-EU");
+    assertThat(event.getEnvironment()).isEqualTo("Staging-EU");
+    event.setEnvironment("Staging West");
+    assertThat(event.getEnvironment()).isNull();
   }
 }

exceptionless-core/src/test/java/com/exceptionless/ExceptionlessConfigurationTest.java

@@ -150,7 +150,16 @@ void environmentIsNormalizedAndKeepsCasing() {
   }
 
   @ParameterizedTest
-  @ValueSource(strings = {"", "  ", "prod\nuction"})
+  @ValueSource(
+      strings = {
+        "",
+        "  ",
+        "prod\nuction",
+        "Staging West",
+        "prod/eu",
+        "-prod",
+        "produ\u00e7\u00e3o"
+      })
   void invalidEnvironmentIsUnspecifiedButConfigured(String value) {
     ExceptionlessConfiguration config = new ExceptionlessConfiguration().environment(value);
     assertThat(config.getEnvironment()).isNull();

exceptionless-core/src/test/java/com/exceptionless/internal/DeploymentEnvironmentTest.java

@@ -14,39 +14,59 @@ class DeploymentEnvironmentTest {
       delimiter = '|',
       value = {
         "production|production",
+        "Staging-EU|Staging-EU",
+        "qa.2|qa.2",
+        "dev_local|dev_local",
+        "a|a",
+        "0|0",
         "  Production |Production",
-        "Prod West|Prod West",
       })
-  void trimsSurroundingWhiteSpaceAndKeepsCasing(String value, String expected) {
+  void validNamesAreTrimmedAndKeepTheirCasing(String value, String expected) {
     assertThat(DeploymentEnvironment.normalize(value)).isEqualTo(expected);
   }
 
   @Test
   void trimsControlWhiteSpaceAndUnicodeSpaces() {
-    // The server trims non-breaking and Unicode spaces too, which String.strip() keeps.
     assertThat(DeploymentEnvironment.normalize("\tProduction\n")).isEqualTo("Production");
     assertThat(DeploymentEnvironment.normalize("\u00a0Production\u00a0")).isEqualTo("Production");
     assertThat(DeploymentEnvironment.normalize("\u2003Production\u2028")).isEqualTo("Production");
     assertThat(DeploymentEnvironment.normalize("\u0085Production")).isEqualTo("Production");
   }
 
-  @Test
-  void keepsInnerCasingAndSpacing() {
-    assertThat(DeploymentEnvironment.normalize(" Prod  West ")).isEqualTo("Prod  West");
-    assertThat(DeploymentEnvironment.normalize(" QA ")).isEqualTo("QA");
-  }
-
   @ParameterizedTest
   @NullSource
-  @ValueSource(strings = {"", " ", "\t\n", " ", " 
"})
+  @ValueSource(strings = {"", " ", "\t\n", "\u00a0", "  "})
   void emptyIsUnspecified(String value) {
     assertThat(DeploymentEnvironment.normalize(value)).isNull();
   }
 
+  @ParameterizedTest
+  @ValueSource(
+      strings = {
+        "Staging West",
+        " Prod  West ",
+        "prod/eu",
+        "prod:eu",
+        "-prod",
+        ".prod",
+        "_prod",
+        "produ\u00e7\u00e3o",
+        "prod\u200b"
+      })
+  void namesOutsideTheRuleAreUnspecifiedAndNeverRewritten(String value) {
+    assertThat(DeploymentEnvironment.normalize(value)).isNull();
+  }
+
+  @Test
+  void nonAsciiLettersAreUnspecifiedEvenWithinTheLengthLimit() {
+    assertThat(DeploymentEnvironment.normalize("\u0130".repeat(64))).isNull();
+  }
+
   @Test
   void allowsSixtyFourCharactersAndRejectsSixtyFive() {
-    assertThat(DeploymentEnvironment.normalize("x".repeat(64))).isEqualTo("x".repeat(64));
-    assertThat(DeploymentEnvironment.normalize("x".repeat(65))).isNull();
+    String name = "a" + "b".repeat(63);
+    assertThat(DeploymentEnvironment.normalize(name)).isEqualTo(name);
+    assertThat(DeploymentEnvironment.normalize("a".repeat(65))).isNull();
   }
 
   @Test