Skip to content

12. Beyond SPARK: the server

The engine is proved, but it cannot run a game by itself. Something has to keep time, accept connections, hold each player's latest controls and run the bots. That is the server, in server/src/. It is ordinary Ada, not SPARK, and this chapter looks at the Ada features it uses and at where the proofs stop.

Library first

The server is a library with a thin program on top. A match is an object you create and stop, so tests can run many matches, and several servers, in one process:

server/src/adawars_server-matches.ads
   type Match (Players : Player_Count) is limited private;

   type Match_Access is access Match;

   --  Starts a match at once. The plan says who is in each seat. With a
   --  Record_Path, the match is recorded there (see Recording).
   function Create
     (Plan : Seat_Plan; Seed : Natural; Record_Path : String := "")
      return Match_Access
   with Pre => Plan'First = 1 and then Plan'Last in Player_Count;

limited private means the type's contents are hidden from users of the package, and that it cannot be copied: a running match is one thing, not a value. access Match is a pointer type. The server allocates matches on the heap, which the engine never does.

The precondition is still there. Contracts work in ordinary Ada too. They are not proved here, but they are checked at run time, as in the engine's tests.

Protected objects

Several things touch a match at once: the clock, each bot, and each HTTP request carrying a player's controls. In Ada, shared data goes in a protected object:

server/src/adawars_server-matches.ads
   protected type State (Players : Player_Count) is
      procedure Start (Seed : Natural);
      procedure Set (P : Player_Id; C : Control);
      --  Steps the world; Used and At_Tick are the controls applied and
      --  the tick they were applied at.
      procedure Tick
        (Used : out Control_Array; At_Tick : out Adawars.Rules.Tick);
...
   private
      W        : World (Players) := New_World (Players, 0);
      Controls : Control_Array (1 .. Players) := [others => Idle];

The data, in the private part, can only be reached through the protected operations. Ada guarantees that procedures run one at a time, with no other operation running, and that functions can run together but never alongside a procedure. No locks are taken by hand, so none can be forgotten.

The tick itself is the engine's Step:

server/src/adawars_server-matches.adb
         W := Adawars.Simulation.Step (W, Controls);

Step's precondition requires a valid world. The server only ever has worlds that came from New_World and Step, both proved to produce valid worlds. So the precondition, checked at run time here, never fails.

Tasks

The clock is a task: a thread, declared as part of the language.

server/src/adawars_server-matches.adb
   task body Clock is
      Next : Ada.Calendar.Time;
   begin
      select
         accept Start;
      or
         terminate;
      end select;
      Next := Ada.Calendar.Clock;
      while M.S.Running loop
         Next := Next + Tick_Length;
         delay until Next;

accept Start waits until another task calls the clock's Start entry: a rendezvous. The select ... or terminate lets the task end quietly if it is never started. delay until Next sleeps to an absolute time, so the ticks do not drift however long each one takes.

Where the proofs stop

The server's job is to move data between the outside world and the engine. At both edges, it hands the decision to proved code.

Coming in, a player's controls go through the proved decoder of chapter 11:

server/src/adawars_server-json.adb
   function Decode_Control (Raw : String) return Decoded is
      --  Renumbered from 1, which also meets Wire.Decode's precondition.
      Text : constant String (1 .. Raw'Length) := Raw;
      D    : constant Adawars.Wire.Decoded := Adawars.Wire.Decode (Text);

Going out, each player gets the proved view of chapter 10, and bots decide from the same view, with no more information than a human has:

server/src/adawars_server-matches.adb
               Bots.Decide (Kind, M.S.Observe (Me), Mem, C);

What is not proved: that the HTTP code is correct, that the clock keeps time, that the bots fly well. A bug there can make the game unplayable. It cannot break a rule, show a player something they should not see, or decide a match wrongly, because none of those are the server's to decide.

That is the design to take away. Put the decisions in a small core you can prove, make everything else a messenger, and make the messages pass through proved code at both ends.

Recap

  • Ordinary Ada keeps contracts, checked at run time.
  • limited private types hide their contents and cannot be copied.
  • Protected objects make shared data safe without hand-written locks.
  • Tasks, entries and delay until are part of the language.
  • Keep the decisions in the proved core, and route the outside world through it.