@astrolabe/server

The grading endpoint (protocol 1) on the standard Fetch API, with the attempt store contract and an in-memory store.

Interfaces

AttemptRecord

One attempt as the grading handler sees it. The key never leaves the server.

Properties

Property	Modifier	Type	Description
checksUsed	readonly	number	Checks counted so far.
createdAt	readonly	string	ISO 8601.
id	readonly	string	-
key	readonly	AnswerKey	-
policy	readonly	AttemptPolicy	-
submitted	readonly	boolean	-

---

AttemptStore

Storage the grading handler needs. Both writes must be atomic per attempt (for example UPDATE ... RETURNING or a conditional update), so parallel requests can neither exceed maxChecks nor submit twice.

Extended by

• MemoryAttemptStore

Methods

get()

get(id): Promise<
  | AttemptRecord
| null>;

null for an unknown attempt.

Parameters

Parameter	Type
id	string

Returns

Promise< | AttemptRecord | null>

recordCheck()

recordCheck(id): Promise<
  | AttemptRecord
| null>;

Counts one check; resolves to the record after counting, or null for an unknown attempt.

Parameters

Parameter	Type
id	string

Returns

Promise< | AttemptRecord | null>

recordSubmit()

recordSubmit(id, submission): Promise<boolean>;

Closes the attempt with its submission; resolves false when it was already submitted (or is unknown).

Parameters

Parameter	Type
id	string
submission	Submission

Returns

Promise<boolean>

---

GradingContext

Which attempt a request is for, as the host resolved it after authorising the request.

Properties

Property	Modifier	Type
attemptId	readonly	string

---

GradingHandlerOptions

Properties

Property	Modifier	Type	Description
attempts	readonly	AttemptStore	-
engine	readonly	Engine	-
now?	readonly	() => number	Clock in milliseconds, for deadlines and submittedAt. Default Date.now.
onError?	readonly	(error, request) => void	Called with every internal failure (a store that throws or returns an inconsistent record, a grading error), for logging. The response stays a generic 500 internal_error either way. Default: nothing.

---

MemoryAttemptStore

Storage the grading handler needs. Both writes must be atomic per attempt (for example UPDATE ... RETURNING or a conditional update), so parallel requests can neither exceed maxChecks nor submit twice.

Extends

• AttemptStore

Methods

create()

create(attempt): Promise<AttemptRecord>;

Starts an attempt with a random id. Throws a TypeError for an invalid key or policy.

Parameters

Parameter	Type
attempt	NewAttempt

Returns

Promise<AttemptRecord>

get()

get(id): Promise<
  | AttemptRecord
| null>;

null for an unknown attempt.

Parameters

Parameter	Type
id	string

Returns

Promise< | AttemptRecord | null>

Inherited from

AttemptStore.get

recordCheck()

recordCheck(id): Promise<
  | AttemptRecord
| null>;

Counts one check; resolves to the record after counting, or null for an unknown attempt.

Parameters

Parameter	Type
id	string

Returns

Promise< | AttemptRecord | null>

Inherited from

AttemptStore.recordCheck

recordSubmit()

recordSubmit(id, submission): Promise<boolean>;

Closes the attempt with its submission; resolves false when it was already submitted (or is unknown).

Parameters

Parameter	Type
id	string
submission	Submission

Returns

Promise<boolean>

Inherited from

AttemptStore.recordSubmit

submission()

submission(id): Promise<Submission | null>;

The stored submission of an attempt, or null.

Parameters

Parameter	Type
id	string

Returns

Promise<Submission | null>

---

NewAttempt

Properties

Property	Modifier	Type
key	readonly	AnswerKey
policy	readonly	AttemptPolicy

---

Submission

What a submit stores: the final answers and the response the student got (re-grade the answers to release more later). The answers are those within their slot kind's length limit, open answers (for the teacher) included: Metadata.open lists their slot ids.

Properties

Property	Modifier	Type
answers	readonly	Answers
response	readonly	SubmitResponse

Type Aliases

GradingHandler

type GradingHandler = (request, context) => Promise<Response>;

Handles POST {endpoint}/check and POST {endpoint}/submit. The host passes the attempt: the handler reads only the action (the final path segment) from the URL, so no part of the URL can point it at another attempt.

Parameters

Parameter	Type
request	Request
context	GradingContext

Returns

Promise<Response>

Variables

ATTEMPT_ID_PATTERN

const ATTEMPT_ID_PATTERN: RegExp;

Attempt ids the handler accepts; anything else is answered 404 not_found.

---

DEADLINE_GRACE_MS

const DEADLINE_GRACE_MS: 30000 = 30_000;

A submit this late after the deadline still counts: the player hands in when its countdown ends, and that request needs a moment to arrive. Later submits are refused like any submit on a closed attempt.

Functions

createGradingHandler()

function createGradingHandler(options): GradingHandler;

Creates the grading endpoint. It answers only protocol-1 requests and never sends key data: check responses carry the GradeResult, and solutions go out with a submit only when the attempt's policy reveals answers.

Parameters

Parameter	Type
options	GradingHandlerOptions

Returns

GradingHandler

---

createMemoryAttemptStore()

function createMemoryAttemptStore(): MemoryAttemptStore;

An AttemptStore in a Map: fine for one process; attempts are lost on restart.

Returns

MemoryAttemptStore