Engine

8.9. Wire format and API🔗

Everything the engine writes reads back, and the API answers as its specification says.

The events a client can send are sendable: they fit the schema and their values print.

🔗inductive predicate
Spec.ApiSpec (now : Rat) : Server → Request → Server → Response → Prop
Spec.ApiSpec (now : Rat) : Server → Request → Server → Response → Prop

What the API must answer, by the reference functions.

Spec.ApiSpec.badRequest {now : Rat} {sv : Server}
  {body : String} {e : WireError} :
  decodeBatch sv.core.schema sv.keys now body =
      Except.error e →
    ApiSpec now sv (Request.append body) sv
      (Response.badRequest e)

a body that is not a batch: rejected as a bad request, nothing changes

Spec.ApiSpec.appended {now : Rat} {sv : Server}
  {body : String} {es : List Event} {st' : State} :
  decodeBatch sv.core.schema sv.keys now body =
      Except.ok es →
    sv.core.appendBatch es = some st' →
      ApiSpec now sv (Request.append body)
        { core := st', keys := sv.keys }
        (Response.appended
          (stamps (sv.core.store.length + 1)
            (List.drop sv.core.store.length st'.store)))

an accepted batch: stored, with its stamps

Spec.ApiSpec.rejected {now : Rat} {sv : Server}
  {body : String} {es : List Event} {st'' : State}
  {rj : Rejection} :
  decodeBatch sv.core.schema sv.keys now body =
      Except.ok es →
    sv.core.appendBatch es = none →
      ∀ (hk : rj.index < es.length),
        sv.core.appendBatch (List.take rj.index es) =
            some st'' →
          st''.rejectionReason es[rj.index] =
              some rj.reason →
            rj.position = st''.store.length + 1 →
              ApiSpec now sv (Request.append body) sv
                (Response.rejected rj)

a rejected batch: the first event the batch can't take, with its reason and position; nothing changes

Spec.ApiSpec.loadFailed {now : Rat} {sv : Server}
  {files : List String} {e : LoadError} :
  loadFiles files = Except.error e →
    ApiSpec now sv (Request.deploy files) sv
      (Response.loadFailed e)

files that don't load: nothing changes

Spec.ApiSpec.deployed {now : Rat} {sv : Server}
  {files : List String} {d : Defs} {st' : State} :
  loadFiles files = Except.ok d →
    sv.core.deploy d.schema d.files = some st' →
      ApiSpec now sv (Request.deploy files)
        { core := st', keys := d.keys } Response.deployed

definitions the deploy takes: the new state and key field names

Spec.ApiSpec.deployRejected {now : Rat} {sv : Server}
  {files : List String} {d : Defs} :
  loadFiles files = Except.ok d →
    sv.core.deploy d.schema d.files = none →
      ApiSpec now sv (Request.deploy files) sv
        Response.deployRejected

definitions the deploy rejects: nothing changes