Skip to main content

How the console writes to the gateway

You change a route in the console and save it. A moment later the gateway takes requests the new way. In between, the change passes through G8's server, which checks it, records it in the audit log and hands it to the gateway of the environment you are in. This page follows one save, of the orders route for example, and says what each step guarantees.

  1. The console checks the form against the object's schema while you type, and sends nothing while a field is wrong or missing.
  2. The server receives the object and refuses what it can tell is wrong without the gateway. For an object that already exists, it reads the gateway's current copy.
  3. The server writes an audit row marked pending. When that row cannot be written, the save stops there and the gateway is never called.
  4. The server asks the gateway whether it would accept the object, and the gateway answers without writing anything. A refusal completes the audit row as failed.
  5. The server sends the accepted object to the gateway, which writes it.
  6. The server reads the object back from the gateway, completes the audit row with the outcome, and answers the console.

The console never talks to the gateway​

Every save goes from the browser to G8's server, at an address that names the environment by its slug, dev for example. The console holds no address of a gateway and no key to one.

The server keeps each environment's Admin API address and admin key, the key sealed. For each save it looks up the environment named in the address and uses that environment's Admin API address and admin key, and no other environment's. A save made in Development reaches Development's gateway and no other. Environments explains what else stays separate. The console calls the gateway the engine, and the messages quoted below keep that word.

Checks before anything is written​

The form is drawn from the object's schema, and the console holds it against that schema as you type. The Raw JSON tab says Validated against the gateway schema as you type. A save is not sent while a field is marked.

On the server, some saves are refused before an audit row exists, so nothing is written and nothing is recorded:

  • The object changed on the gateway since you opened it. The console sends the version of the object it loaded, and the server refuses the save when the gateway holds another. The page says The object changed on the engine, and offers to reload or to overwrite.
  • A certificate whose key and certificate do not belong together.
  • A logger that would write request records into the records of another environment; see Where request records go.

Two refusals do leave a row, completed as failed. A secret sent back still holding its mask is refused, and the console says A secret still holds its mask. Type the real value, or leave the field untouched. A delete in a protected environment that does not name what it removes is refused, and the console says This environment is protected, so a delete has to name what it removes.

The audit row comes first​

Before the gateway is called, the server writes the audit row of the change with the result pending: who, which action, which object, in which environment. Only once that row is in the database does the server go on. When it cannot be written, the server refuses the save with 503 and calls nothing. The console says The change was not recorded, so the engine was not touched. Try again when the console's database is reachable.

This order gives the audit log one guarantee. No row means no change: nothing reaches the gateway through G8 without its row already written.

Then the gateway checks the object by its own rules, the last word on what it accepts. The console says as much when you create something: The engine has the final say when you create it.

  • Before anything is written, the server asks the gateway whether it would accept the whole object, and the gateway answers without writing anything. A refusal completes the row as failed with the gateway's reasons, and the console places them on the fields they name. Only an object the gateway accepted is then sent to be written, whole.
  • A certificate is the exception. A change to one sends only the fields you changed, so its stored private key stays. The gateway checks those fields as it writes them, and a refusal completes the row as failed in the same way.

Once the gateway has accepted it, the server reads the object back and completes the row as a success. The row then holds the object before and after the change, with every secret in it masked. The audit log shows that pair as the change's difference. When only the read back fails, the change is made and recorded as a success, and the console says it could not refresh the page.

When the gateway does not answer​

A gateway that cannot be reached, or that fails with a server error, leaves the outcome open. The change may have been made before the answer was lost. The server then reads the object once more and compares it with the copy from before the save.

  • The object changed as asked: the row is completed as a success.
  • The object did not change: the row is completed as failed.
  • The gateway cannot be read either: the audit log shows the row as Failed, and its details say the outcome is unknown. The change may still be on the gateway, so open the object to see what the gateway holds.

A row stays pending only when the server never completed it, because the server stopped between the two writes or its database refused the completion. The Audit log shows such a row as In progress for its first minute and as Outcome unknown after that. Its page then says The engine was called, but the completion of this change was never recorded. The engine may or may not hold the change; open the object and compare it before repeating the change.

Changes to G8 itself​

Users, roles, the directory connection and sign-ins live in G8's own database, not on a gateway. For those the audit row is written in the same database transaction as the change. Either both are stored or neither is.

G8 dev