Module machi_flu1_client

Erlang API for the Machi FLU TCP protocol version 1.

Description

Erlang API for the Machi FLU TCP protocol version 1.

This client API handles low-level PDU serialization/deserialization and low-level TCP session management, e.g. open, receive, write, close. The API for higher-level session management and Machi state management can be found in machi_proxy_flu1_client and machi_cr_client.

TODO This EDoc was written first, and the EDoc and also -type and -spec definitions for machi_proxy_flu1_client and machi_cr_client must be improved.

Protocol origins

The protocol implemented here is an artisanal, hand-crafted, silly thing that was very quick to put together for a "demo day" proof of concept. It will almost certainly be replaced with something else, both in terms of wire format and better code separation of serialization/deserialization vs. network transport management, etc.

For the moment, this module implements a rudimentary TCP-based protocol as the sole supported access method to the server, sequencer, and projection store. Conceptually, those three services are independent and ought to have their own protocols. As a practical matter, there is no need for wire protocol compatibility. Furthermore, from the perspective of failure detection, it is very convenient that all three FLU-related services are accessed using the same single TCP port.

Data Types

chunk()

chunk() = binary() | iolist()

client can use either

chunk_csum()

chunk_csum() = {file_offset(), chunk_size(), binary()}

chunk_pos()

chunk_pos() = {file_offset(), chunk_size(), file_name_s()}

chunk_s()

chunk_s() = binary()

server always uses binary()

chunk_size()

chunk_size() = non_neg_integer()

epoch_csum()

epoch_csum() = binary()

epoch_id()

epoch_id() = {epoch_num(), epoch_csum()}

epoch_num()

epoch_num() = -1 | non_neg_integer()

error_general()

error_general() = bad_arg | wedged

file_info()

file_info() = {file_size(), file_name_s()}

file_name()

file_name() = binary() | list()

file_name_s()

file_name_s() = binary()

server reply

file_offset()

file_offset() = non_neg_integer()

file_prefix()

file_prefix() = binary() | list()

file_size()

file_size() = non_neg_integer()

inet_host()

inet_host() = inet:ip_address() | inet:hostname()

inet_port()

inet_port() = inet:port_number()

port_wrap()

port_wrap() = {w, atom(), term()}

projection()

projection() = #projection_v1{}

projection_type()

projection_type() = public | private

Function Index

append_chunk/4Append a chunk (binary- or iolist-style) of data to a file with Prefix.
append_chunk/5Append a chunk (binary- or iolist-style) of data to a file with Prefix.
append_chunk_extra/5Append a chunk (binary- or iolist-style) of data to a file with Prefix and also request an additional Extra bytes.
append_chunk_extra/6Append a chunk (binary- or iolist-style) of data to a file with Prefix and also request an additional Extra bytes.
checksum_list/3Fetch the list of chunk checksums for File.
checksum_list/4Fetch the list of chunk checksums for File.
connect/1
connected_p/1
delete_migration/3Restricted API: Delete a file after it has been successfully migrated.
delete_migration/4Restricted API: Delete a file after it has been successfully migrated.
disconnect/1
get_all_projections/2Get all projections from the FLU's projection store.
get_all_projections/3Get all projections from the FLU's projection store.
get_latest_epochid/2Get the latest epoch number + checksum from the FLU's projection store.
get_latest_epochid/3Get the latest epoch number + checksum from the FLU's projection store.
list_all_projections/2Get all epoch numbers from the FLU's projection store.
list_all_projections/3Get all epoch numbers from the FLU's projection store.
list_files/2Fetch the list of all files on the remote FLU.
list_files/3Fetch the list of all files on the remote FLU.
quit/1Quit & close the connection to remote FLU.
read_chunk/5Read a chunk of data of size Size from File at Offset.
read_chunk/6Read a chunk of data of size Size from File at Offset.
read_latest_projection/2Get the latest projection from the FLU's projection store for ProjType
read_latest_projection/3Get the latest projection from the FLU's projection store for ProjType
read_projection/3Read a projection Proj of type ProjType.
read_projection/4Read a projection Proj of type ProjType.
trunc_hack/3Restricted API: Truncate a file after it has been successfully erasure coded.
trunc_hack/4Restricted API: Truncate a file after it has been successfully erasure coded.
wedge_status/1Fetch the wedge status from the remote FLU.
wedge_status/2Fetch the wedge status from the remote FLU.
write_chunk/5Restricted API: Write a chunk of already-sequenced data to File at Offset.
write_chunk/6Restricted API: Write a chunk of already-sequenced data to File at Offset.
write_projection/3Write a projection Proj of type ProjType.
write_projection/4Write a projection Proj of type ProjType.

Function Details

append_chunk/4

append_chunk(Sock::port_wrap(), EpochID::epoch_id(), Prefix::file_prefix(), Chunk::chunk()) -> {ok, chunk_pos()} | {error, error_general()} | {error, term()}

Append a chunk (binary- or iolist-style) of data to a file with Prefix.

append_chunk/5

append_chunk(Host::inet_host(), TcpPort::inet_port(), EpochID::epoch_id(), Prefix::file_prefix(), Chunk::chunk()) -> {ok, chunk_pos()} | {error, error_general()} | {error, term()}

Append a chunk (binary- or iolist-style) of data to a file with Prefix.

append_chunk_extra/5

append_chunk_extra(Sock::port_wrap(), EpochID::epoch_id(), Prefix::file_prefix(), Chunk::chunk(), ChunkExtra::chunk_size()) -> {ok, chunk_pos()} | {error, error_general()} | {error, term()}

Append a chunk (binary- or iolist-style) of data to a file with Prefix and also request an additional Extra bytes.

For example, if the Chunk size is 1 KByte and Extra is 4K Bytes, then the file offsets that follow Chunk's position for the following 4K will be reserved by the file sequencer for later write(s) by the write_chunk() API.

append_chunk_extra/6

append_chunk_extra(Host::inet_host(), TcpPort::inet_port(), EpochID::epoch_id(), Prefix::file_prefix(), Chunk::chunk(), ChunkExtra::chunk_size()) -> {ok, chunk_pos()} | {error, error_general()} | {error, term()}

Append a chunk (binary- or iolist-style) of data to a file with Prefix and also request an additional Extra bytes.

For example, if the Chunk size is 1 KByte and Extra is 4K Bytes, then the file offsets that follow Chunk's position for the following 4K will be reserved by the file sequencer for later write(s) by the write_chunk() API.

checksum_list/3

checksum_list(Sock::port_wrap(), EpochID::epoch_id(), File::file_name()) -> {ok, [chunk_csum()]} | {error, error_general() | no_such_file | partial_read} | {error, term()}

Fetch the list of chunk checksums for File.

checksum_list/4

checksum_list(Host::inet_host(), TcpPort::inet_port(), EpochID::epoch_id(), File::file_name()) -> {ok, [chunk_csum()]} | {error, error_general() | no_such_file} | {error, term()}

Fetch the list of chunk checksums for File.

connect/1

connect(P_srvr) -> any()

connected_p/1

connected_p(X1) -> any()

delete_migration/3

delete_migration(Sock::port_wrap(), EpochID::epoch_id(), File::file_name()) -> ok | {error, error_general() | no_such_file} | {error, term()}

Restricted API: Delete a file after it has been successfully migrated.

delete_migration/4

delete_migration(Host::inet_host(), TcpPort::inet_port(), EpochID::epoch_id(), File::file_name()) -> ok | {error, error_general() | no_such_file} | {error, term()}

Restricted API: Delete a file after it has been successfully migrated.

disconnect/1

disconnect(WS) -> any()

get_all_projections/2

get_all_projections(Sock::port_wrap(), ProjType::projection_type()) -> {ok, [projection()]} | {error, term()}

Get all projections from the FLU's projection store.

get_all_projections/3

get_all_projections(Host::inet_host(), TcpPort::inet_port(), ProjType::projection_type()) -> {ok, [projection()]} | {error, term()}

Get all projections from the FLU's projection store.

get_latest_epochid/2

get_latest_epochid(Sock::port_wrap(), ProjType::projection_type()) -> {ok, epoch_id()} | {error, term()}

Get the latest epoch number + checksum from the FLU's projection store.

get_latest_epochid/3

get_latest_epochid(Host::inet_host(), TcpPort::inet_port(), ProjType::projection_type()) -> {ok, epoch_id()} | {error, term()}

Get the latest epoch number + checksum from the FLU's projection store.

list_all_projections/2

list_all_projections(Sock::port_wrap(), ProjType::projection_type()) -> {ok, [non_neg_integer()]} | {error, term()}

Get all epoch numbers from the FLU's projection store.

list_all_projections/3

list_all_projections(Host::inet_host(), TcpPort::inet_port(), ProjType::projection_type()) -> {ok, [non_neg_integer()]} | {error, term()}

Get all epoch numbers from the FLU's projection store.

list_files/2

list_files(Sock::port_wrap(), EpochID::epoch_id()) -> {ok, [file_info()]} | {error, term()}

Fetch the list of all files on the remote FLU.

list_files/3

list_files(Host::inet_host(), TcpPort::inet_port(), EpochID::epoch_id()) -> {ok, [file_info()]} | {error, term()}

Fetch the list of all files on the remote FLU.

quit/1

quit(Sock::port_wrap()) -> ok

Quit & close the connection to remote FLU.

read_chunk/5

read_chunk(Sock::port_wrap(), EpochID::epoch_id(), File::file_name(), Offset::file_offset(), Size::chunk_size()) -> {ok, chunk_s()} | {error, error_general() | not_written | partial_read} | {error, term()}

Read a chunk of data of size Size from File at Offset.

read_chunk/6

read_chunk(Host::inet_host(), TcpPort::inet_port(), EpochID::epoch_id(), File::file_name(), Offset::file_offset(), Size::chunk_size()) -> {ok, chunk_s()} | {error, error_general() | not_written | partial_read} | {error, term()}

Read a chunk of data of size Size from File at Offset.

read_latest_projection/2

read_latest_projection(Sock::port_wrap(), ProjType::projection_type()) -> {ok, projection()} | {error, not_written} | {error, term()}

Get the latest projection from the FLU's projection store for ProjType

read_latest_projection/3

read_latest_projection(Host::inet_host(), TcpPort::inet_port(), ProjType::projection_type()) -> {ok, projection()} | {error, not_written} | {error, term()}

Get the latest projection from the FLU's projection store for ProjType

read_projection/3

read_projection(Sock::port_wrap(), ProjType::projection_type(), Epoch::epoch_num()) -> {ok, projection()} | {error, not_written} | {error, term()}

Read a projection Proj of type ProjType.

read_projection/4

read_projection(Host::inet_host(), TcpPort::inet_port(), ProjType::projection_type(), Epoch::epoch_num()) -> {ok, projection()} | {error, not_written} | {error, term()}

Read a projection Proj of type ProjType.

trunc_hack/3

trunc_hack(Sock::port_wrap(), EpochID::epoch_id(), File::file_name()) -> ok | {error, error_general() | no_such_file} | {error, term()}

Restricted API: Truncate a file after it has been successfully erasure coded.

trunc_hack/4

trunc_hack(Host::inet_host(), TcpPort::inet_port(), EpochID::epoch_id(), File::file_name()) -> ok | {error, error_general() | no_such_file} | {error, term()}

Restricted API: Truncate a file after it has been successfully erasure coded.

wedge_status/1

wedge_status(Sock::port_wrap()) -> {ok, {boolean(), pv1_epoch()}} | {error, term()}

Fetch the wedge status from the remote FLU.

wedge_status/2

wedge_status(Host::inet_host(), TcpPort::inet_port()) -> {ok, {boolean(), pv1_epoch()}} | {error, term()}

Fetch the wedge status from the remote FLU.

write_chunk/5

write_chunk(Sock::port_wrap(), EpochID::epoch_id(), File::file_name(), Offset::file_offset(), Chunk::chunk()) -> ok | {error, error_general()} | {error, term()}

Restricted API: Write a chunk of already-sequenced data to File at Offset.

write_chunk/6

write_chunk(Host::inet_host(), TcpPort::inet_port(), EpochID::epoch_id(), File::file_name(), Offset::file_offset(), Chunk::chunk()) -> ok | {error, error_general()} | {error, term()}

Restricted API: Write a chunk of already-sequenced data to File at Offset.

write_projection/3

write_projection(Sock::port_wrap(), ProjType::projection_type(), Proj::projection()) -> ok | {error, written} | {error, term()}

Write a projection Proj of type ProjType.

write_projection/4

write_projection(Host::inet_host(), TcpPort::inet_port(), ProjType::projection_type(), Proj::projection()) -> ok | {error, written} | {error, term()}

Write a projection Proj of type ProjType.


Generated by EDoc, May 20 2015, 12:36:35.