aether_lib 0.1.2

A library that provides P2P communication for Prototype Aether. Contains the implementations of the Aether Protocol. This library can be used to develop P2P applications.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

[![Build](https://github.com/Prototype-Aether/Aether-Lib/actions/workflows/build.yml/badge.svg)](https://github.com/Prototype-Aether/Aether-Lib/actions/workflows/build.yml)
[![Tests](https://github.com/Prototype-Aether/Aether-Lib/actions/workflows/tests.yml/badge.svg)](https://github.com/Prototype-Aether/Aether-Lib/actions/workflows/tests.yml)
[![License](https://img.shields.io/badge/License-GPL--3.0-blue)](https://github.com/Prototype-Aether/Aether-Lib/blob/main/LICENSE)
# Aether Lib

Prototype Aether is a General Purpose Peer to Peer communication protocol. It allows
developers to develop P2P applications using an easy to use library.

The Rust library `aether_lib` contains the actual implementation of the protocol.
It can be used directly as a Rust library to develop applications. However, the
[Aether Service](https://github.com/Prototype-Aether/Aether-Service) which is currently
under development is recommended way to interact with Aether.

The documentation for Aether Lib can be found [here](https://docs.rs/aether_lib/latest/aether_lib/)

# Installation

Add `aether_lib` to your project in `Cargo.toml` as

```toml
[dependencies]
aether_lib = "0.1.1"
```

# Basic Usage

The following examples show how to use `aether_lib` for P2P communications.

[A tracker server](https://github.com/Prototype-Aether/Aether-Tracker) is required
for the network to function. The tracker server helps in peer discovery and provides
public identities of the peers for UDP Holepunching (peer introduction).

## Starting a client

In order to use P2P communication, you need to initialize an `Aether` instance. This
can be done as follows -

```rust
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use aether_lib::peer::Aether;

// The socker address of a tracker server to be used
let tracker_addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(1, 2, 3, 4)), 8982);

// Initalize the link with a given tracker address
let aether = Aether::new(tracker_addr);

// Start the link
aether.start();
```

## Connecting to a peer

To start a P2P link to another peer, use the function `connect()` in `Aether`.

```rust
let peer_uid = String::from("<peer-uid-here>");
aether.connect(&peer_uid);
```

## Sending bytes to another peer

All communications happen in form of bytes, so you can send `Vec<u8>`. For example,
strings can be converted to bytes using `string.into_bytes()` (this converts to UTF-8
encoding) and from UTF-8 encoded bytes using `let string = String::from_utf8(bytes)`.

In order to send bytes to a user `peer_uid` you can use `send_to()`

```rust
let message = String::from("Hello");
let bytes = message.into_bytes();
aether.send_to(&peer_uid, bytes).unwrap();
```

## Receiving bytes from another peer

In order to receive bytes from a user `peer_uid` you can use `recv_from()`

```rust
let bytes = aether.recv_from(&peer_uid).unwrap();
let message = String::from_utf8(bytes).unwrap();
```