Bootstrap method: file

The “file” bootstrap method allows you to initialize a Flock group by loading a group view from a file. This assumes that a JSON file with the Flock format has been created beforehand.

When to use

Use the “file” bootstrap method when:

• You have a pre-generated group view file to distribute

• You’re restarting a service and want to restore the previous group

• You want to bootstrap multiple processes with the same view

File format

Flock group view files use JSON format and typically have a .flock extension. A group view file contains:

• List of members (addresses and provider IDs)

• Metadata (key-value pairs)

• Digest (version information)

Example group view file:

{
    "members":[
        {"address":"na+sm://27842-0","provider_id":42},
        {"address":"na+sm://27843-0","provider_id":42}
    ],
    "metadata":{
        "__config__":"{}",
        "__type__":"static"
    }
}

Configuration

In Bedrock configuration:

{
    "libraries": [
        "libflock-bedrock-module.so"
    ],
    "providers": [
        {
            "type": "flock",
            "name": "my_flock_provider",
            "provider_id": 42,
            "config": {
                "bootstrap": "file",
                "file": "mygroup.flock",
                "group": {
                    "type": "static",
                    "config": {}
                }
            }
        }
    ]
}

The “file” field specifies the path to the group view file. This can be an absolute path or a relative path from the working directory.

In C code

To load a group view from a file programmatically:

/*
 * (C) 2024 The University of Chicago
 *
 * See COPYRIGHT in top-level directory.
 */
#include <assert.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <margo.h>
#include <flock/flock-server.h>
#include <flock/flock-bootstrap.h>

int main(int argc, char** argv)
{
    if(argc != 2) {
        fprintf(stderr, "Usage: %s <group_file>\n", argv[0]);
        return -1;
    }

    const char* group_file = argv[1];

    // Initialize Margo
    margo_instance_id mid = margo_init("na+sm", MARGO_SERVER_MODE, 0, 0);
    assert(mid);

    // Get server address
    hg_addr_t my_address;
    margo_addr_self(mid, &my_address);
    char addr_str[256];
    hg_size_t addr_str_size = 256;
    margo_addr_to_string(mid, addr_str, &addr_str_size, my_address);
    margo_addr_free(mid, my_address);

    printf("Server running at address %s\n", addr_str);

    // Initialize provider args
    struct flock_provider_args args = FLOCK_PROVIDER_ARGS_INIT;
    flock_group_view_t initial_view = FLOCK_GROUP_VIEW_INITIALIZER;
    args.initial_view = &initial_view;

    uint16_t provider_id = 42;
    int ret;

    // Bootstrap from file: read existing group view from a JSON file
    ret = flock_group_view_init_from_file(group_file, &initial_view);

    if(ret != FLOCK_SUCCESS) {
        fprintf(stderr, "Failed to bootstrap from file %s\n", group_file);
        margo_finalize(mid);
        return -1;
    }

    printf("Bootstrapped group from file: %s\n", group_file);
    printf("Group size: %zu\n", initial_view.members.size);

    // Print all members in the initial view
    for(size_t i = 0; i < initial_view.members.size; i++) {
        printf("  Member %zu: %s (provider_id=%u)\n",
               i,
               initial_view.members.data[i].address,
               initial_view.members.data[i].provider_id);
    }

    // Configure with static backend
    const char* config = "{ \"group\":{ \"type\":\"static\", \"config\":{} } }";

    // Register provider
    flock_provider_t provider;
    ret = flock_provider_register(mid, provider_id, config, &args, &provider);
    assert(ret == FLOCK_SUCCESS);

    printf("Flock provider registered\n");

    // Wait for finalize
    margo_wait_for_finalize(mid);

    return 0;
}

The flock_group_view_init_from_file function takes:

• The path to the file

• A pointer to the group view to initialize

This function reads the file, parses the JSON, and populates the group view structure.

Creating group view files

You can create group view files in several ways:

1. From an existing provider

Configure a provider to write its view to a file:

{
    "config": {
        "bootstrap": "self",
        "file": "mygroup.flock",
        "group": {
            "type": "static",
            "config": {}
        }
    }
}

The provider will write its view to the specified file at initialization.

2. Manually

You can create the JSON file manually using a text editor, following the format shown above.