Head chunks, WAL, and flushing

1def appendSample(seriesId, ts, value):
2    entry = (seriesId, ts, value)
3    if wal_enabled:
4        walAppend(entry)             # disk first
5    headAppend(seriesId, ts, value)  # RAM second
6    return ok                        # ack: both have it

1def walAppend(entry):
2    record = encode(entry)
3    wal_file.write(record)           # append-only, sequential
4    if fsync_policy == 'always':
5        wal_file.fsync()             # durable before ack
6    # else: OS flushes on its own schedule

1def headAppend(seriesId, ts, value):
2    head = head_chunks[seriesId]    # one per active series
3    head.samples.append((ts, value)) # sub-ms in-memory
4    if head.samples_in == head.capacity:
5        sealHeadChunk(seriesId)     # write file + mmap RO
6 
7def sealHeadChunk(seriesId):
8    head = head_chunks[seriesId]
9    path = write_compressed(head)   # gorilla-encoded bytes
10    sealed_chunks.append(mmap_readonly(path))
11    head_chunks[seriesId] = new_head()  # fresh, empty

1def recoverFromCrash():
2    head_chunks = {}                 # RAM was wiped
3    for entry in wal.scan_sequentially():
4        headAppend(*entry)           # rebuild fill levels
5    for path in chunks_dir.list():
6        sealed_chunks.append(mmap_readonly(path))
7    # without WAL: partial heads are gone forever