Strata

Tree-based time-period tracking

---

Specification

Datastricture

The datastructure is, at a given moment in time, a stack, but overall is a tree. Its elements are periods.
A period consists of a start timestamp, an optional (i.e. unset until applicable) end timestamp, and a list of child periods.
A period's bounds (start & end) MUST NOT exceed the bounds of its parent period.
A period's bounds MUST NOT overlap with the bounds of its siblings (the start/end times MAY be equal).

The result is something similar to the way a flamegraph is constructed.

The operations performed on the stack/tree are:

• push (creates a child period to the current deepest active period)
• pop (ends the current deepest period)
• popandpush (ends the current deepest period and pushes a new period, a sibling to the period that was ended)

Periods have a url-safe string identifier, which is used for representing the current period stack (or any period stack).

An example of a stack represented as a string: tournament/race-1/lap-1 for a tree like:

tournament/
	race-1/
		lap-1
		lap-2
		lap-3
	race-2/
		lap-1

or, for the current stack in this tree: tournament/race-2/lap-1

Reading

The information for a period is accessed over HTTP and returned in JSON.

For example:

GET /tournament/race-1/lap-1 returns

{
	"start": 1785172958,
	"end": null,
	"children": []
}

Or for its parent:

GET /tournament/race-1 returns

{
	"start": 1785172958,
	"end": null,
	"children": ["lap-1"]
}

Writing

Operating on the current stack is done using PUT and DELETE requests.

For example, given a beginning stack of tournament/:

PUT /tournament/race-1 -- Pushes the child period
PUT /tournament/race-1/lap-1 -- Same as above
PUT /tournament/race-1/lap-2 -- Since the current state is /tournament/race-1/lap-1, this pops & pushes the new period
DELETE /tournament/race-1 -- Pops the race period. The stack is back to its beginning state, but with child nodes finished