Rename all env vars, even ones from other systems.

Author: Ughuuu

.env.example

@@ -4,6 +4,11 @@
 # is also what the admin Settings page renders. Values shown are defaults;
 # a commented line means the default applies when the variable is unset.
 #
+# Every name is derived from its declaration as GAMEND_<GROUP>_<KEY>, with
+# no exceptions. Variables other software reads (RELEASE_COOKIE for the
+# release boot script, FLY_* from the platform) are not settings and are
+# not listed here.
+#
 # Settings can equally be configured in Elixir, which skips this file
 # entirely:
 #
@@ -59,36 +64,9 @@
 # DNS name whose A/AAAA records list the other nodes, polled at boot.
 # GAMEND_CLUSTER_DNS_QUERY=
 
-# Extra BEAM flags, e.g. -proto_dist inet6_tcp for IPv6-only networking.
-# Inherited: this name is defined by other software.
-# ERL_AFLAGS=
-
-# Inherited: this name is defined by other software.
-# FLY_APP_NAME=
-
-# Inherited: this name is defined by other software.
-# FLY_PRIVATE_IP=
-
-# Inherited: this name is defined by other software.
-# FLY_REGION=
-
 # Shared fallback URL used by the cache and rate limiter when neither sets
 # its own.
-# Inherited: this name is defined by other software.
-# REDIS_URL=
-
-# Shared secret every node in the cluster must match.
-# Secret — never commit a real value.
-# Inherited: this name is defined by other software.
-# RELEASE_COOKIE=
-
-# name (long names) or sname. Read by the release boot script.
-# Inherited: this name is defined by other software.
-# RELEASE_DISTRIBUTION=
-
-# This node's name. Must be unique across the cluster.
-# Inherited: this name is defined by other software.
-# RELEASE_NODE=
+# GAMEND_CLUSTER_REDIS_URL=
 
 # ──────────────────────────────────────────────────────────────────────────
 # Content & plugins
@@ -123,21 +101,16 @@
 # How long a request waits to check out a connection, in milliseconds.
 # GAMEND_DB_POOL_TIMEOUT=10000
 
-# Inherited: this name is defined by other software.
-# POSTGRES_DB=
+# GAMEND_DB_POSTGRES_DB=
 
-# Inherited: this name is defined by other software.
-# POSTGRES_HOST=
+# GAMEND_DB_POSTGRES_HOST=
 
 # Secret — never commit a real value.
-# Inherited: this name is defined by other software.
-# POSTGRES_PASSWORD=
+# GAMEND_DB_POSTGRES_PASSWORD=
 
-# Inherited: this name is defined by other software.
-# POSTGRES_PORT=5432
+# GAMEND_DB_POSTGRES_PORT=5432
 
-# Inherited: this name is defined by other software.
-# POSTGRES_USER=
+# GAMEND_DB_POSTGRES_USER=
 
 # GAMEND_DB_QUERY_TIMEOUT=15000
 
@@ -158,10 +131,9 @@
 
 # GAMEND_DB_SQLITE_WAL_AUTOCHECKPOINT=2000
 
-# Full ecto:// URL. Takes precedence over the individual POSTGRES_* values.
+# Full ecto:// URL. Takes precedence over the individual postgres_* values.
 # Secret — never commit a real value.
-# Inherited: this name is defined by other software.
-# DATABASE_URL=
+# GAMEND_DB_URL=
 
 # ──────────────────────────────────────────────────────────────────────────
 # Email
@@ -681,9 +653,8 @@
 # Public hostname, used to build URLs and OAuth redirect URIs.
 # GAMEND_HTTP_HOST=localhost
 
-# TCP port the HTTP listener binds. Injected by most platforms.
-# Inherited: this name is defined by other software.
-# PORT=4000
+# TCP port the HTTP listener binds.
+# GAMEND_HTTP_PORT=4000
 
 # http or https. Defaults to http for localhost, https otherwise.
 # GAMEND_HTTP_SCHEME=

.github/workflows/build-and-check.yml

@@ -121,9 +121,8 @@ jobs:
 
           docker network create smoke-net
 
-          # POSTGRES_* are inherited names — platforms provision them, so they
-          # are the only database variables the server reads. Using a derived
-          # GAMEND_DB_POSTGRES_* name here silently configures nothing.
+          # The postgres container reads its own POSTGRES_* names to
+          # initialise; the server reads ours. They are deliberately distinct.
           {
             echo "GAMEND_AUTH_SECRET_KEY_BASE=$(head -c 48 /dev/urandom | base64 | tr -d '\n')"
             echo "GAMEND_HTTP_HOST=localhost"
@@ -143,10 +142,10 @@ jobs:
             done
 
             {
-              echo "POSTGRES_HOST=smoke-db"
-              echo "POSTGRES_USER=postgres"
-              echo "POSTGRES_PASSWORD=postgres"
-              echo "POSTGRES_DB=game_server_prod"
+              echo "GAMEND_DB_POSTGRES_HOST=smoke-db"
+              echo "GAMEND_DB_POSTGRES_USER=postgres"
+              echo "GAMEND_DB_POSTGRES_PASSWORD=postgres"
+              echo "GAMEND_DB_POSTGRES_DB=game_server_prod"
             } >> smoke.env
           fi
 

apps/game_server_core/lib/game_server/cluster.ex

@@ -3,10 +3,17 @@ defmodule GameServer.Cluster do
   Erlang distribution, needed for multi-node deployments and the partitioned
   L2 cache.
 
-  Every name here is inherited: `RELEASE_*` and `ERL_AFLAGS` are read by the
-  BEAM and by Elixir's release scripts before any of our code runs, and the
-  `FLY_*` values are injected by the platform. They are declared so the admin
-  page can show what the node actually came up with.
+  Only `dns_query` and `redis_url` are settings — values this server reads.
+  The rest of a clustered deployment is configured through variables *other
+  software* reads before any of our code runs: `RELEASE_DISTRIBUTION`,
+  `RELEASE_NODE` and `RELEASE_COOKIE` are consumed by the release boot script,
+  `ERL_AFLAGS` by `erl` itself, and the `FLY_*` values are injected by the
+  platform.
+
+  Declaring those as settings would be a lie: renaming them onto our convention
+  would not rename what the BEAM and the platform read, it would leave the
+  settings permanently empty. `environment/0` reports them for the admin page
+  as observations rather than settings.
   """
 
   use GameServer.Settings.Provider,
@@ -18,38 +25,26 @@ defmodule GameServer.Cluster do
     doc: "DNS name whose A/AAAA records list the other nodes, polled at boot."
   )
 
-  setting(:release_distribution, :string,
-    env: "RELEASE_DISTRIBUTION",
-    external: true,
-    doc: "name (long names) or sname. Read by the release boot script."
-  )
-
-  setting(:release_node, :string,
-    env: "RELEASE_NODE",
-    external: true,
-    doc: "This node's name. Must be unique across the cluster."
+  setting(:redis_url, :string,
+    doc: "Shared fallback URL used by the cache and rate limiter when neither sets its own."
   )
 
-  setting(:release_cookie, :string,
-    env: "RELEASE_COOKIE",
-    external: true,
-    secret: true,
-    doc: "Shared secret every node in the cluster must match."
-  )
+  @external ~w(RELEASE_DISTRIBUTION RELEASE_NODE RELEASE_COOKIE ERL_AFLAGS
+               FLY_APP_NAME FLY_PRIVATE_IP FLY_REGION)
 
-  setting(:erl_aflags, :string,
-    env: "ERL_AFLAGS",
-    external: true,
-    doc: "Extra BEAM flags, e.g. -proto_dist inet6_tcp for IPv6-only networking."
-  )
+  @secret ~w(RELEASE_COOKIE)
 
-  setting(:redis_url, :string,
-    env: "REDIS_URL",
-    external: true,
-    doc: "Shared fallback URL used by the cache and rate limiter when neither sets its own."
-  )
+  @doc """
+  The clustering variables other software reads, with their current values,
+  for display only.
 
-  setting(:fly_app_name, :string, env: "FLY_APP_NAME", external: true)
-  setting(:fly_private_ip, :string, env: "FLY_PRIVATE_IP", external: true)
-  setting(:fly_region, :string, env: "FLY_REGION", external: true)
+  These are not settings and cannot be renamed onto our convention — the BEAM
+  and the platform read these exact names.
+  """
+  @spec environment() :: [%{name: String.t(), value: String.t() | nil, secret: boolean()}]
+  def environment do
+    for name <- @external do
+      %{name: name, value: System.get_env(name), secret: name in @secret}
+    end
+  end
 end

apps/game_server_core/lib/game_server/database.ex

@@ -6,7 +6,7 @@ defmodule GameServer.Database do
   `adapter` here is documentation and admin display rather than something a
   restart can change — the app refuses to start on a stale build and says so.
 
-  `DATABASE_URL` and the `POSTGRES_*` family are inherited names: platforms
+  `GAMEND_DB_URL` and the `POSTGRES_*` family are inherited names: platforms
   provision them, and renaming them would break every managed-database
   attachment.
   """
@@ -22,17 +22,15 @@ defmodule GameServer.Database do
   )
 
   setting(:url, :string,
-    env: "DATABASE_URL",
-    external: true,
     secret: true,
-    doc: "Full ecto:// URL. Takes precedence over the individual POSTGRES_* values."
+    doc: "Full ecto:// URL. Takes precedence over the individual postgres_* values."
   )
 
-  setting(:postgres_host, :string, env: "POSTGRES_HOST", external: true)
-  setting(:postgres_port, :integer, default: 5432, env: "POSTGRES_PORT", external: true)
-  setting(:postgres_user, :string, env: "POSTGRES_USER", external: true)
-  setting(:postgres_password, :string, env: "POSTGRES_PASSWORD", external: true, secret: true)
-  setting(:postgres_db, :string, env: "POSTGRES_DB", external: true)
+  setting(:postgres_host, :string)
+  setting(:postgres_port, :integer, default: 5432)
+  setting(:postgres_user, :string)
+  setting(:postgres_password, :string, secret: true)
+  setting(:postgres_db, :string)
 
   setting(:ipv6, :boolean,
     default: false,

apps/game_server_core/lib/game_server/settings/provider.ex

@@ -16,8 +16,13 @@ defmodule GameServer.Settings.Provider do
   The declaration is the only place a setting is written down. Its environment
   variable name is **derived** — `<ROOT>_<GROUP>_<KEY>`, e.g.
   `GAMEND_RETENTION_CHAT_MESSAGES_DAYS` — so the key and its env var can never
-  disagree. Pass `env:` only for the handful of names other software owns
-  (`PORT`, `DATABASE_URL`), which should also carry `external: true`.
+  disagree. There is no way to pin a different name: every setting follows the
+  convention, without exception.
+
+  A variable that *other* software reads (`RELEASE_COOKIE` for the release boot
+  script, `FLY_REGION` from the platform) is not a setting and does not belong
+  here — renaming our declaration would not rename what that software reads.
+  Report those separately; `GameServer.Cluster.environment/0` is the example.
 
   Values are read back with `GameServer.Settings.get/2`, which checks
   `Application.get_env(app, module)` and falls back to the compiled default. A
@@ -33,10 +38,6 @@ defmodule GameServer.Settings.Provider do
   - `:root` — first segment of the env name. Defaults to `"GAMEND"`; a plugin
     passes its own (`root: "POLYGLOT"`).
   - `:label` — display name for the group. Defaults to a capitalised `:group`.
-  - `:env_prefix` — replaces the derived `<ROOT>_<GROUP>_` prefix for every
-    setting in the provider, so `LIMIT_MAX_PAGE_SIZE` can keep its name while
-    the group is `:limits`. A transitional escape hatch for names that predate
-    the convention; a per-setting `env:` still wins over it.
 
   ## Options for `setting/3`
 
@@ -50,22 +51,18 @@ defmodule GameServer.Settings.Provider do
     them to hold.
   - `:with` — sibling keys forming a complete-or-empty group. All unset is
     silent; a partial set trips `:required`.
-  - `:env` — override the derived env var name. For inherited names only.
-  - `:external` — this name belongs to other software; the viewer files it
-    under "Inherited" rather than implying we own it.
   """
 
   @types [:string, :integer, :float, :boolean, :atom, :list, :log_level]
 
-  @setting_opts [:default, :doc, :secret, :required, :when, :with, :env, :external]
+  @setting_opts [:default, :doc, :secret, :required, :when, :with]
 
   @doc false
   defmacro __using__(opts) do
     app = Keyword.fetch!(opts, :app)
     group = Keyword.fetch!(opts, :group)
     root = Keyword.get(opts, :root, "GAMEND")
     label = Keyword.get(opts, :label) || group |> to_string() |> String.capitalize()
-    env_prefix = Keyword.get(opts, :env_prefix)
 
     quote do
       import GameServer.Settings.Provider, only: [setting: 2, setting: 3]
@@ -76,7 +73,6 @@ defmodule GameServer.Settings.Provider do
       @gamend_settings_group unquote(group)
       @gamend_settings_root unquote(root)
       @gamend_settings_label unquote(label)
-      @gamend_settings_env_prefix unquote(env_prefix)
 
       @before_compile GameServer.Settings.Provider
     end
@@ -98,16 +94,8 @@ defmodule GameServer.Settings.Provider do
     group = Module.get_attribute(module, :gamend_settings_group)
     root = Module.get_attribute(module, :gamend_settings_root)
     label = Module.get_attribute(module, :gamend_settings_label)
-    env_prefix = Module.get_attribute(module, :gamend_settings_env_prefix)
 
-    context = %{
-      module: module,
-      app: app,
-      group: group,
-      root: root,
-      label: label,
-      env_prefix: env_prefix
-    }
+    context = %{module: module, app: app, group: group, root: root, label: label}
 
     definitions =
       module
@@ -155,10 +143,9 @@ option(s) #{inspect(unknown)}; expected one of #{inspect(@setting_opts)}"
       label: label,
       type: type,
       default: Keyword.get(opts, :default),
-      env: Keyword.get(opts, :env) || derive_env(root, group, key, context.env_prefix),
+      env: derive_env(root, group, key),
       doc: Keyword.get(opts, :doc, ""),
       secret: Keyword.get(opts, :secret, false),
-      external: Keyword.get(opts, :external, false),
       required: required,
       when: Keyword.get(opts, :when),
       with: Keyword.get(opts, :with, [])
@@ -168,16 +155,10 @@ option(s) #{inspect(unknown)}; expected one of #{inspect(@setting_opts)}"
   @doc """
   The environment variable name for a group and key: `<ROOT>_<GROUP>_<KEY>`.
 
-  A provider-level `env_prefix` replaces the `<ROOT>_<GROUP>_` part.
+  The only way a setting gets a name. There is no override.
   """
-  @spec derive_env(String.t(), atom(), atom(), String.t() | nil) :: String.t()
-  def derive_env(root, group, key, env_prefix \\ nil)
-
-  def derive_env(_root, _group, key, env_prefix) when is_binary(env_prefix) do
-    env_prefix <> String.upcase(to_string(key))
-  end
-
-  def derive_env(root, group, key, nil) do
+  @spec derive_env(String.t(), atom(), atom()) :: String.t()
+  def derive_env(root, group, key) do
     [root, to_string(group), to_string(key)]
     |> Enum.map_join("_", &String.upcase/1)
   end

apps/game_server_core/lib/mix/tasks/gamend.settings.env_example.ex

@@ -63,6 +63,11 @@ defmodule Mix.Tasks.Gamend.Settings.EnvExample do
     # is also what the admin Settings page renders. Values shown are defaults;
     # a commented line means the default applies when the variable is unset.
     #
+    # Every name is derived from its declaration as GAMEND_<GROUP>_<KEY>, with
+    # no exceptions. Variables other software reads (RELEASE_COOKIE for the
+    # release boot script, FLY_* from the platform) are not settings and are
+    # not listed here.
+    #
     # Settings can equally be configured in Elixir, which skips this file
     # entirely:
     #
@@ -105,11 +110,7 @@ defmodule Mix.Tasks.Gamend.Settings.EnvExample do
   defp annotations(definition) do
     [
       requirement_note(definition),
-      if(definition.secret, do: "# Secret — never commit a real value.\n", else: []),
-      if(definition.external,
-        do: "# Inherited: this name is defined by other software.\n",
-        else: []
-      )
+      if(definition.secret, do: "# Secret — never commit a real value.\n", else: [])
     ]
   end
 

apps/game_server_web/config/dev.exs

@@ -1,10 +1,10 @@
 import Config
 
-if System.get_env("DATABASE_URL") ||
-     (System.get_env("POSTGRES_HOST") && System.get_env("POSTGRES_USER")) do
+if System.get_env("GAMEND_DB_URL") ||
+     (System.get_env("GAMEND_DB_POSTGRES_HOST") && System.get_env("GAMEND_DB_POSTGRES_USER")) do
   database_url =
-    System.get_env("DATABASE_URL") ||
-      "ecto://#{System.get_env("POSTGRES_USER")}:#{System.get_env("POSTGRES_PASSWORD")}@#{System.get_env("POSTGRES_HOST")}:#{System.get_env("POSTGRES_PORT", "5432")}/#{System.get_env("POSTGRES_DB", "game_server_web_dev")}"
+    System.get_env("GAMEND_DB_URL") ||
+      "ecto://#{System.get_env("GAMEND_DB_POSTGRES_USER")}:#{System.get_env("GAMEND_DB_POSTGRES_PASSWORD")}@#{System.get_env("GAMEND_DB_POSTGRES_HOST")}:#{System.get_env("GAMEND_DB_POSTGRES_PORT", "5432")}/#{System.get_env("GAMEND_DB_POSTGRES_DB", "game_server_web_dev")}"
 
   config :game_server_core, GameServer.Repo,
     url: database_url,