PSF-HTTP API: an authenticated HTTP admin API for the web portal, plus game-side fixes

.gitignore

@@ -34,3 +34,13 @@ logs/
 pscrypto-lib/
 .bsp/
 project/project/
+
+# Compose reads `.env` from this directory automatically, for variable substitution in the compose
+# files. That makes it the natural home for host-specific values and secrets, so it must never be
+# committed.
+.env
+
+# Local-only compose overlay: host-specific addresses, published ports and dev secrets. Auto-merged
+# by `docker compose` without being referenced anywhere, which is exactly how it gets committed by
+# accident.
+docker-compose.override.yml

Dockerfile

@@ -12,6 +12,7 @@ COPY --from=builder /PSF-LoginServer/server/target/pack/ /usr/local
 
 EXPOSE 51000/udp
 EXPOSE 51001/udp
+# The PSF-HTTP API.
 EXPOSE 51002/tcp
 
 CMD ["psforever-server"]

server/src/main/resources/db/migration/V019__PortalSchedule.sql

@@ -0,0 +1,76 @@
+-- Scheduled actions the portal performs against the world server.
+--
+-- WHY THIS LIVES HERE
+-- The portal has no database of its own -- it reads and writes everything through the PSF-HTTP API,
+-- deliberately, so the login server owns its data outright. A schedule still has to be durable
+-- (it must survive a portal restart) and it has to be shared (two portal processes must agree on
+-- whether a run already happened), so it belongs in this database even though nothing in the world
+-- server reads it. Hence the `portal` prefix: these rows are the portal's, stored here because this
+-- is where durable shared state lives.
+--
+-- TRIGGERS
+-- A schedule may carry a time trigger, a condition trigger, or both. With both, either one firing
+-- runs the action -- they are alternatives, not a conjunction, because "at 04:00, and also whenever
+-- the server empties out" is the useful reading and "only at 04:00 if the server is also empty" is
+-- not what anyone asks for.
+--
+--   time      at_time 'HH:MM' plus every_days (1 = daily, 7 = weekly)
+--   condition players_below / players_above a threshold
+--
+-- CONDITIONS FIRE ON A CROSSING, NOT A STATE
+-- "Below 10 players" is true continuously all night, so firing on the state would re-apply the
+-- layout every time the evaluator ticked. `armed` is what makes it an edge: it is cleared when the
+-- condition fires and set again only once the population has gone back the other way, so one
+-- crossing produces exactly one run. It is stored rather than kept in memory because a portal
+-- restart in the middle of a quiet night must not re-arm and fire a second time.
+
+CREATE TABLE IF NOT EXISTS "portalschedule" (
+  "id"            SERIAL PRIMARY KEY,
+  "name"          TEXT        NOT NULL,
+  -- What to do. Only 'continent_layout' exists today; the column is text so adding another action
+  -- is a row rather than a migration.
+  "action"        TEXT        NOT NULL,
+  -- The action's parameters as JSON. For 'continent_layout' this is the `control` map that
+  -- /zones/apply-layout takes: zone number -> { building local id -> faction id }.
+  "payload"       TEXT        NOT NULL,
+  "enabled"       BOOLEAN     NOT NULL DEFAULT TRUE,
+
+  -- Time trigger. Both NULL when the schedule is condition-only.
+  -- 'HH:MM' in the server's own local time, kept as text because that is what it is -- a wall-clock
+  -- time of day, not an instant, and storing it as a timestamp would invite a date to come with it.
+  "at_time"       TEXT,
+  "every_days"    INTEGER,
+
+  -- Condition trigger. NULL when the schedule is time-only.
+  "condition"     TEXT,
+  "threshold"     INTEGER,
+  -- Whether the condition is ready to fire; see the note above on crossings.
+  "armed"         BOOLEAN     NOT NULL DEFAULT TRUE,
+
+  -- Bookkeeping. `last_run` is also the claim: a process wins the right to run a schedule by
+  -- advancing it, so two portals cannot both act on the same due schedule.
+  "last_run"      TIMESTAMP,
+  "last_result"   TEXT,
+  "created_by"    TEXT        NOT NULL,
+  "created"       TIMESTAMP   NOT NULL DEFAULT NOW(),
+
+  CONSTRAINT "portalschedule_action_known"
+    CHECK ("action" IN ('continent_layout')),
+  CONSTRAINT "portalschedule_condition_known"
+    CHECK ("condition" IS NULL OR "condition" IN ('players_below', 'players_above')),
+  -- A condition without a threshold, or a threshold without a condition, is a half-written trigger
+  -- that would either never fire or fire on nothing.
+  CONSTRAINT "portalschedule_condition_complete"
+    CHECK (("condition" IS NULL) = ("threshold" IS NULL)),
+  -- Same for the time trigger.
+  CONSTRAINT "portalschedule_time_complete"
+    CHECK (("at_time" IS NULL) = ("every_days" IS NULL)),
+  CONSTRAINT "portalschedule_every_days_positive"
+    CHECK ("every_days" IS NULL OR "every_days" >= 1),
+  -- A schedule with neither trigger can never run, so it is not a schedule.
+  CONSTRAINT "portalschedule_has_a_trigger"
+    CHECK ("at_time" IS NOT NULL OR "condition" IS NOT NULL)
+);
+
+-- The evaluator reads the enabled rows every tick and nothing else ever scans this table.
+CREATE INDEX IF NOT EXISTS "portalschedule_enabled_idx" ON "portalschedule" ("enabled");

server/src/main/resources/db/migration/V020__PortalScheduleActions.sql

@@ -0,0 +1,14 @@
+-- Let the portal decide which scheduled actions exist.
+--
+-- V019 pinned `action` to a single value with a CHECK, on the assumption that constraining it here
+-- was free. It is not: the actions are implemented in the portal, in a registry it can extend, and
+-- a constraint in this database means every new action needs a migration in a repository that has
+-- nothing to do with it -- and a deploy ordering, since the portal would be writing a value the
+-- database still refused.
+--
+-- The action is validated where it is implemented instead: the portal refuses an unknown action at
+-- creation, with a message naming the ones it does know. What this database keeps enforcing is the
+-- part that is genuinely structural and outlives any particular action -- that a schedule has at
+-- least one trigger, and that each trigger it has is complete.
+
+ALTER TABLE "portalschedule" DROP CONSTRAINT IF EXISTS "portalschedule_action_known";

server/src/main/scala/net/psforever/server/Server.scala

@@ -16,7 +16,7 @@ import ch.qos.logback.classic.joran.JoranConfigurator
 import io.sentry.{Sentry, SentryOptions}
 import net.psforever.actors.net.{LoginActor, MiddlewareActor, SocketSetup, SocketSetupInfo, SocketPane}
 import net.psforever.actors.session.SessionActor
-import net.psforever.login.psadmin.PsAdminActor
+import net.psforever.actors.api.{AdminHttpService, ScheduledActionsActor}
 import net.psforever.login._
 import net.psforever.objects.Default
 import net.psforever.objects.zones._
@@ -148,16 +148,17 @@ object Server {
       name = SocketPane.SocketPaneKey.id
     )
 
-    val adminListener = system.actorOf(
-      classic.Props(
-        new TcpListener(
-          classOf[PsAdminActor],
-          "psadmin-client-",
-          InetAddress.getByName(Config.app.admin.bind),
-          Config.app.admin.port
-        )
-      ),
-      "psadmin-tcp-endpoint"
+    val adminEndpoint = system.actorOf(
+      classic.Props(new AdminHttpService(Config.app.admin.bind, Config.app.admin.port)),
+      "admin-http-endpoint"
+    )
+
+    // Scheduled actions. Evaluated here rather than in the portal because a schedule that fires at
+    // four in the morning has to be evaluated by a process that is running at four in the morning,
+    // and this is the process that is up whenever the game is.
+    val scheduledActions = system.actorOf(
+      classic.Props(new ScheduledActionsActor()),
+      "scheduled-actions"
     )
 
     logger.info(

src/main/resources/application.conf

@@ -1,5 +1,6 @@
-# The socket bind address for all net.psforever.services except admin. 127.0.0.1 is the
-# default for local testing, for public servers use 0.0.0.0 instead.
+# The socket bind address for the game sockets (login and world). 127.0.0.1 is the default for
+# local testing, for public servers use 0.0.0.0 instead. The PSF-HTTP API binds separately,
+# under `admin` below.
 bind = 127.0.0.1
 
 # The public host name or IP address. Used to forward clients from the login
@@ -30,9 +31,10 @@ world {
   server-type = development
 }
 
-# Admin API configuration
+# PSF-HTTP API configuration. The `admin` key name is kept for compatibility: it is what
+# CONFIG_FORCE_admin_bind and existing deployments set.
 admin {
-  # TCP listening port
+  # HTTP listening port
   port = 51002
 
   # The socket bind address