[−][src]Crate namaste
Namaste
Project
- Repository: https://bitbucket.org/haibison/namaste-rs
- License: Nice License 1.0.0 (see LICENSE file at root directory of
master
branch) - This project follows Semantic Versioning 2.0.0
Features
- Handling locks amongst processes via TCP.
Design
Identifier
An identifier - ID - is a 64-byte array, which matches an SHA3-512 hash.
Server and client
-
Server starts on a fixed TCP port, and listens for clients.
-
"Book" command:
-
When a new client connects to, they are expected to send 4 pieces of information:
- A one-byte "book" command.
- Global ID. This ID is used within a lifetime of the server, as an identification of the client.
- Handshake ID - must be different to above ID. This ID is used for the server to communicate with client.
- Client's local TCP server port, consisting of 2 bytes, in big-endian order.
-
Server then connects to the client's local server, sends the handshake ID, reads an ID and compares it with the first one above.
-
If the verification passes, server stores client ID in memory, and sends back one non-zero byte to client.
-
If the verification does not passes, server sends back one zero byte to client.
-
-
"Check out" command sends one-byte command, ID and handshake ID.
Limits
- Server stores all IDs in memory. So if it crashes, they are lost.
- Server relies on a fixed loop-back IP address (
DEFAULT_IP
) as a protection against external Denial-of-service attacks. However, it is not protected against attacks from internal programs running on a same machine. - Client side will ask system to grant it a random TCP server port. On most systems, TCP ports are limited.
About crashing issue: we always strive to code carefully. If you find out bugs, we are thankful if you file reports in project repository.
Usage
You should only rely on this library for limited small amount of locks between your program's processes. For instance, this library can help with single-instance designed programs.
Frequently Answered Questions
Why not Unix Domain Socket?
UDS has a good design, but its implementation has some serious flaws:
- Already-bound file path can be deleted. Any new binding to that path will silently take control of current one.
- Linux has an extension to UDS, which is called abstract sockets. Its design is very good, and can totally replace this library. However its documentation clearly states that it is not portable.
Why Namaste
?
Namaste
uses abstract Linux sockets underneath. It was made because, as stated above, abstract socket is a good design. Using
that struct requires unsafe
blocks because it calls libc
.
Why not file locks?
- On Unix, locked files can still be deleted.
Alternatives
Currently the authors are not aware of any projects similar to this one.
Building server
-
Via Cargo:
~> cargo install namaste --version=x.y.z --features=bin
-
From source:
~> # Clone a specific version via tag name ~> git clone --branch=x.y.z --depth=1 -- https://bitbucket.org/haibison/namaste-rs namaste-x.y.z/ ~> cd namaste-x.y.z/ ~> cargo build --release --features=bin
Examples
It is expected that the system already has Namaste server running!
use namaste::client::Client; // ID must be a constant. const NAMASTE_ID: namaste::Id = [...]; fn main() { // You should generate new handshake ID each time you call Client::book(). let handshake_id = ...; match Client::book(NAMASTE_ID, handshake_id, None, namaste::DEFAULT_RW_TIMEOUT) { Ok(Some(client)) => { run_main_job(); match client.check_out() { Ok(true) => println!("Successfully checked out of Namaste server"), Ok(false) => eprintln!("Couldn't check out of Namaste server"), Err(err) => eprintln!("Failed checking out of Namaste server: {}", err), }; }, Ok(None) => eprintln!("Another instance is running"), Err(err) => eprintln!("Failed connecting to Namaste server: {}", err), }; }
Other notes
To generate an ID, you can get help from Dia-Hammer:
$ hammer sha3-512 --limit=65536 --format=hex-array -- /dev/urandom
To generate a handshake ID, you can use tiny-keccak
.
Modules
client | Client |
server | Server |
version_info |
|
Constants
CODE_NAME | Crate code name |
DEFAULT_IP | Default IP address, used for both server and client |
DEFAULT_RW_TIMEOUT | Default read/write timeout: 3 seconds |
ID | ID of this crate |
NAME | Crate name |
RELEASE_DATE | Crate release date (year/month/day) |
TAG | Tag, which can be used for logging... |
VERSION | Crate version |
Functions
cmp_ids | Compares IDs |
read_id | Reads ID |
Type Definitions
Id | Identifier |
Result | Result type used in this crate |