Value Store API Reference

Ask for a brand new block, representing an ImmutableBlock.

The address of an ImmutableBlock is based on its owner public key and the payload of the block, given by the MakeImmutableBlockRequest. N.B. The Block is not pushed yet.

• Go
• C++
• Python

# Create the immutable block.
block = vs.MakeImmutableBlock(
  MakeImmutableBlockRequest(data = b'some data'))
# Actually insert the block.
vs.Insert(InsertRequest(block = block))

// Create the immutable block with a payload.
iblock, _ := client.MakeImmutableBlock(
               context.Background(),
               &vs.MakeImmutableBlockRequest{Data: []byte("some data")})
// Actually insert the block.
client.Insert(context.Background(), &vs.InsertRequest{Block: iblock})

// Create an immutable block creation request.
::memo::vs::MakeImmutableBlockRequest make_block;
// Set the payload.
make_block.set_data("some data");
// Create an empty block.
::memo::vs::Block block;
{
  // Create a context.
  grpc::ClientContext ctx;
  // Construct the immutable block and store it in `block`.
  auto status = vs->MakeImmutableBlock(&ctx, make_block, &block);
  if (!status.ok())
    throw std::runtime_error("Cannot make immutable block");
}
// Create a insertion response.
::memo::vs::InsertResponse insertion;
{
  // Create a context.
  grpc::ClientContext ctx;
  // Create an insertion request.
  ::memo::vs::InsertRequest insert;
  // Set the block to the insertion request using the setter.
  //
  // N.B. `mutable_block` is to access to a mutable version of the attribute
  // `block`. It's not correlated with MutableBlock or ImmutableBlock.
  insert.mutable_block()->CopyFrom(block);
  // Actually insert the block.
  auto status = vs->Insert(&ctx, insert, &insertion);
  if (!status.ok())
    throw std::runtime_error("Cannot insert block");
}

Ask for a brand new Block, representing a MutableBlock.

The address is chosen randomly by the key-value store. Hence, the MakeMutableBlockRequest has no attributes. N.B. The Block is not pushed yet.

• Go
• C++
• Python

# Create the block, empty.
block = vs.MakeMutableBlock(MakeMutableBlockRequest())
# Set the block payload.
block.data_plain = b'some data'
# Actually insert the block.
vs.Insert(InsertRequest(block = block))

// Create the block, empty.
mblock, _ := client.MakeMutableBlock(context.Background(),
                                     &vs.MakeMutableBlockRequest{})
// Create a payload.
payload := []byte("some data")
// Set the block payload.
mblock.Payload = &vs.Block_DataPlain{payload}
// Actually insert the block.
client.Insert(context.Background(),
              &vs.InsertRequest{Block: mblock})

// Create an insertion request.
::memo::vs::InsertRequest insert;
// Create a mutable block creation request.
::memo::vs::MakeMutableBlockRequest empty;
// Construction.
{
   // Set a context.
   grpc::ClientContext ctx;
   // Create the mutable block and store the result in the insertion request
   // field.
   //
   // N.B. `mutable_` is to access to a mutable version of the attribute
   // `block`. It's not correlated with MutableBlock or ImmutableBlock.
   auto status = vs->MakeMutableBlock(&ctx, empty, insert.mutable_block());
   if (!status.ok())
     throw std::runtime_error("Cannot make mutable block");
   // Set the payload.
   insert.mutable_block()->set_data_plain("some data");
}
{
  // Create an insertion response.
  ::memo::vs::InsertResponse insertion;
  // Set a context.
  grpc::ClientContext ctx;
  // Actually insert the block.
  auto status = vs->Insert(&ctx, insert, &insertion);
  if (!status.ok())
    throw std::runtime_error("Cannot insert block");
}

Fetch the block at given address.

• Go
• C++
• Python

# Fetch a block at the address given by `address`.
block = vs.Fetch(FetchRequest(address = address)).block

// Fetch a block at the address given by `address`.
res, _ := client.Fetch(context.Background(), &vs.FetchRequest{Address: address})
block := res.Block

// Create a fetch response.
::memo::vs::FetchResponse res;
// Create a context.
grpc::ClientContext ctx;
// Create a fetch request.
::memo::vs::FetchRequest fetch;
// Set the address to fetch request.
fetch.set_address(address);
// Actually fetch the block.
{
  auto status = vs->Fetch(&ctx, fetch, &res);
  if (!status.ok())
    throw std::runtime_error("Unable to fetch block");
}
// Retrieve the block.
auto block = res.block();

Insert a new Block.

The Block to insert is given by the InsertRequest. The Block should have been created by using Make<...>Block. Insert returns an InsertResponse, containing the information related to the Insertion.

• Go
• C++
• Python

# Given a block `block`, insert the block.
vs.Insert(InsertRequest(block = block))

// Given a block `block`, insert the block.
//
client.Insert(context.Background(),
              &vs.InsertRequest{Block: block})

// XXX: wrong.
//
// Depending on the type of block (mutable or immutable), insertion differs.
//
// Given a mutable block `mblock`, insert the mutable block.
{
  // Create an insert response.
  ::memo::vs::InsertResponse insertion;
  // Create a context.
  grpc::ClientContext ctx;
  // Create an insertion request.
  ::memo::vs::InsertRequest insert;
  // Set the block to the insertion request using the setter.
  //
  // N.B. `mutable_block` is to access to a mutable version of the attribute
  // `block`. It's not correlated with MutableBlock or ImmutableBlock.
  insert.mutable_block()->set_data_plain("some data");
  // Actually insert the block.
  auto status = vs->Insert(&ctx, insert, &insertion);
  if (!status.ok())
    throw std::runtime_error("Cannot insert block");
}
// Given a immutable block with a payload already set, insert a immutable block.
{
  // Create an insert response.
  ::memo::vs::InsertResponse insertion;
  // Create a context.
  grpc::ClientContext ctx;
  // Create an insertion request.
  ::memo::vs::InsertRequest insert;
  // Set the block to the insertion request using the setter.
  //
  // N.B. `mutable_block` is to access to a mutable version of the attribute
  // `block`. It's not correlated with MutableBlock or ImmutableBlock.
  insert.mutable_block()->CopyFrom(block);
  // Actually insert the block.
  auto status = vs->Insert(&ctx, insert, &insertion);
  if (!status.ok())
    throw std::runtime_error("Cannot insert block");
}

Update an existing block.

The address and the new content of the Block are given by the UpdateRequest. Update doesn't perform an upsert, hence, the update will fail if the block doesn't exist, but also you are not allowed to update it. The UpdateResponse will contain the information related to the result of the insertion attempt.

• Go
• C++
• Python

# Given a block `block` and a payload `payload`.
#
# Set the block new payload.
block.data_plain = payload
# Perform the update.
#
# Setting the update request `decrypt_data` field to `True` so the `block`
# field of the update response will be decrypted. This is useful if you need
# to fix potential conflicts resulting of the update.
response = vs.Update(UpdateRequest(block = block,
                                   decrypt_data = True))
if response.current:
  # Solve conflict here, `response.current` contains the current version of
  # the block in the value-store.
  pass

// Given a block `block` and a payload `payload`.
//
// Set the block new payload.
block.Payload = &vs.Block_DataPlain{payload}
// Perform the update.
//
// Setting the update request `DecryptData` field to `true` so the `Block`
// field of the update response will be decrypted. This is useful if you need
// to fix potential conflicts resulting of the update.
status, _ := client.Update(context.Background(),
                           &vs.UpdateRequest{Block: block,
                                             DecryptData: true})
// If there is a conflict.
if (status.GetCurrent() != nil) {
  // Solve conflict here, `response.block` contains the current version of
  // the block in the value-store.
}

// Given a block `block` and a payload `payload`.
//
// Create an update response.
::memo::vs::UpdateResponse response;
// Set the block new payload.
block.set_data_plain(payload);
{
  // Create a context.
  grpc::ClientContext ctx;
  // Create an update request.
  ::memo::vs::UpdateRequest update;
  // Set the update request `block` field with the updated version of the block.
  update.mutable_block()->CopyFrom(block);
  // Set the update request `decrypt_data` field to `true` so the `block` field
  // of the update response will be decrypted. This is useful if you need to fix
  // potential conflicts resulting of the update.
  update.set_decrypt_data(true);
  // Actually update the block.
  auto status = vs->Update(&ctx, update, &response);
  if (!status.ok())
    throw std::runtime_error("Unable to update the block");
  // If there is a conflict.
  if (response.has_current())
  {
    // Solve conflict here, `response.block` contains the current version of
    // the block in the value-store.
  }
}

Erase the block at the given address.

The address of the Block is given by the DeleteRequest. The ability to remove a Block is determined by two factors: The existence of the Block and the permission to delete it. The DeleteResponse will contain the information related to result of the deletion attempt.

• Go
• C++
• Python

# Given an address `address`, remove the block at `address`.
#
vs.Delete(DeleteRequest(address = address))

// Given an address `address`, remove the block at `address`.
//
_, err := client.Delete(context.Background(),
                        &vs.DeleteRequest{Address: address})
if err != nil {
  log.Fatal("Unable to remove block")
}

// Given an address `address`, remove the block at `address`.

// Create a remove request.
::memo::vs::DeleteRequest remove;
// Create a remove status.
::memo::vs::DeleteResponse removal;
// Set the address.
remove.set_address(address);
// Create a context.
grpc::ClientContext ctx;
// Actually remove the block.
auto status = vs->Delete(&ctx, remove, &removal);
if (!status.ok())
  throw std::runtime_error("Cannot remove block");