MerFS

At first boot the device’s authority service creates a pump-app scope and grants it to the pump application. The grant carries a 32 MiB quota, a 256-file limit and a 2-second volatility ceiling. The application holds that handle and nothing above it.

merfs_status grant_pump_app(merfs_system *system,
    const merfs_scope *pump_scope,
    const uint8_t grant_id[MERFS_IDENTITY_BYTES], merfs_scope **pump_app)
{
    merfs_grant_options grant;
    merfs_publication_options durable_now;
    merfs_grant_options_default(&grant);
    memcpy(grant.identity, grant_id, MERFS_IDENTITY_BYTES);
    grant.max_logical_bytes = UINT64_C(32) << 20;  /* 32 MiB of files */
    grant.max_files = 256u;
    grant.max_delay_ns = UINT64_C(2000000000);     /* at most 2 s volatile */
    grant.max_open_files = 16u;
    grant.max_builders = 2u;
    merfs_publication_options_default(&durable_now);
    durable_now.max_delay_ns = 0;
    return merfs_system_grant_scope(system, pump_scope, &grant, &durable_now,
        pump_app);
}

Each night the application first opens the schedule it is about to replace. The open returns an observation token naming the exact version it saw, and the handle reads that version and no other.

merfs_status read_schedule(merfs_scope *pump_app, uint8_t *out,
    size_t capacity, merfs_observation *seen)
{
    merfs_file *file = NULL;
    uint64_t offset = 0;
    size_t got = 0;
    merfs_status status = merfs_file_open(pump_app, "schedule", 8u, seen,
        &file);
    if (status != MERFS_OK) return status;
    if (merfs_file_body_bytes(file) > capacity) {
        merfs_file_close(&file);
        return MERFS_LIMIT;
    }
    while (status == MERFS_OK && offset < merfs_file_body_bytes(file)) {
        status = merfs_file_read_body(file, offset, out + offset,
            capacity - (size_t)offset, &got);
        offset += got;
    }
    merfs_file_close(&file);
    return status;
}

The application stages the new schedule in 16 KB chunks under the same name, then commits with the token. The complete body must validate as one Rune document before a single checked root publication gives it the name. With a zero volatility window, the commit returns only after that root is durable.

merfs_status replace_schedule(merfs_scope *pump_app,
    const merfs_observation *seen, const chest *schedule,
    const chest_source *metadata, merfs_completion *done)
{
    merfs_builder *builder = NULL;
    merfs_publication_options durable_now;
    const uint8_t *bytes = (const uint8_t *)chest_bytes(schedule);
    size_t size = chest_size(schedule), sent = 0;
    merfs_status status = merfs_builder_begin(pump_app, "schedule", 8u,
        MERFS_PUBLISH_REPLACE, seen, metadata, &builder);
    if (status != MERFS_OK) return status;
    while (sent < size) {
        size_t step = size - sent < 16384u ? size - sent : 16384u;
        status = merfs_builder_append(builder, bytes + sent, step);
        if (status != MERFS_OK) {
            merfs_builder_abort(&builder);
            return status;
        }
        sent += step;
    }
    merfs_publication_options_default(&durable_now);
    durable_now.max_delay_ns = 0;  /* return only after the new root is durable */
    return merfs_builder_commit(&builder, &durable_now, done);
}

One night a technician’s console and the operations center both publish a schedule. The later commit carries a token for a version that is no longer the newest. MerFS returns a conflict instead of overwriting, and the application rereads before it decides.

merfs_status update_schedule(merfs_scope *pump_app, const chest *schedule,
    const chest_source *metadata, uint8_t *scratch, size_t capacity)
{
    merfs_observation seen;
    merfs_completion done;
    merfs_status status = read_schedule(pump_app, scratch, capacity, &seen);
    if (status != MERFS_OK) return status;
    status = replace_schedule(pump_app, &seen, schedule, metadata, &done);
    if (status == MERFS_CONFLICT) {
        /* a newer schedule was published after our read: reread, decide again */
        status = read_schedule(pump_app, scratch, capacity, &seen);
    }
    return status;
}