bash-com/README.md

# bash socket utility

## 1. Listen

Binding an input creates a listening socket on a local port and binds the socket data to a local accessible buffer (accessible with the native `read` call).

```bash
bind-input $id $port;
```

*Arguments:*
- `$id` is a unique arbitrary name you must give to the listening binding
- `$port` is the number of the local port to listen to (between 1024 and 49151)

*Execution:*
- The `bind-input` execution will last until the socket is created, then it will move it to a background process and print its *PID*.
- In order to close properly the `bind-input`, you must kill its *PID* with one of the 3 following signals: SIGINT, SIGHUP, SIGTERM. Note that you must not use *SIGKILL* because it won't trigger the "*proper closing*" routine.


*Exemple:*

Let's say that you want to listen to port 9999, then read every second. You want to ignore empty messages (if nothing received), and end the program when you receive the message "**END**".

```bash
#/bin/bash

# 1. Create the listening socket + store PID in /tmp
bind-input input1 9999 > /tmp/get_bg_pid;

# 2. Store PID in a variable
bound_pid="`cat /tmp/get_bg_pid`";

# 3. Now the socket is listening, you can read every 1 sec
while true; do

    # 3.1. Read received data from port 9999
    message="`read input1`";

    # 3.2. Ignore empty messages
    [[ -z "$message" ]] && sleep 1 && continue;

    # 3.3. Exit while() loop if received "END"
    [[ "$message" = "END" ]] && break;

    # 3.4. Wait 1 sec
    sleep 1;

done;

# 4. Kill 'bind-input' with signal SIGINT, SIGHUP or SIGTERM
kill -INT $bound_pid;
```










## 2. Connect

Binding an output creates a local accessible buffer (accessible with the native `write` call) bound to a socket connecting to a certain host and port.

```bash
bind-output $id $host $port;
```

*Arguments:*
- `$id` is a unique arbitrary name you must give to the output binding
- `$host` is the hostname (IP addr. or resolvable) of the machine to connect to.
- `$port` is the number of the remote port to connect to (between 1024 and 49151)

*Execution:*
- The `bind-output` execution will last until the socket is created, then it will move it to a background process and print its *PID*.
- In order to close properly the `bind-output`, you must kill its *PID* with one of the 3 following signals: SIGINT, SIGHUP, SIGTERM. Note that you must not use *SIGKILL* because it won't trigger the "*proper closing*" routine.


*Exemple:*

Let's say that you want to connect to port 192.168.0.2 at port 9999, wait 2 seconds, send a message, wait 1 second and send the "**END**" message.

```bash
#/bin/bash

# 1. Create the connecting socket + store PID in /tmp
bind-output output1 192.168.0.2 9999 > /tmp/get_bg_pid;

# 2. Store PID in a variable
bound_pid="`cat /tmp/get_bg_pid`";

# 3. Wait for sending first message
sleep 2;
write output1 "some message\nwith\tescapable\e[1mcharaters\e[0m";

# 4. Wait for sending "END" message
sleep 1;
write output1 "END";

# 5. Kill 'bind-output' with signal SIGINT, SIGHUP or SIGTERM
kill -INT $bound_pid;
```

## 3. Network trigger

The programs `trigger-send` and `trigger-wait` allows *signals* to be send over the network (private or public).
- `trigger-wait` will wait for a signal to exit.
- `trigger-send` will send a signal to a remote host.

### **trigger-wait**

```bash
trigger-wait $key $port
```

*Arguments:*
- `$key` is a secret string that the sender will have to match.
- `$port` is the local listening port (between 1024 and 49151).

*Note:* The reading delay is set to 0.5 seconds not to overuse the processor.

*Exemple:*

Let's say you want to wait for a signal on port 9999 then launch some command (for example `read input1`).

```bash
trigger-wait somekey123 9999; read input1;
```

### **trigger-send**

```bash
trigger-wait $key $host $port
```

*Arguments:*
- `$key` is the same secret string used by the receiver.
- `$host` is the remote hostname (IP addr. or resolvable) to send the messag eto.
- `$port` is the remote port to send the message to (between 1024 and 49151).

*Exemple:*

Let's say you want to execute a long command (sleep 5), then send the trigger to 192.168.0.2 port 9999.

```bash
sleep 5; trigger-send somekey123 192.168.0.2 9999;
```


## 4. Daemon pool

This package includes a purpose-specific implementation:
- `master` pushes a pool of daemons (infinite scripts echoing things over time) bound to a pool receiver.
- `pool` waits for daemons to be started to bind input buffers.

### Pool receiver

The `pool` commands allows you to wait for daemons on a port.

```bash
pool $key $port
```

*Arguments:*
- `$key` is the key for the pool receiver, the _master_ must match it in order for the communication to be validated.
- `$port` is the number of the local port to listen on (between 1024 and 49151).

*Execution:*
1. Waits for incoming _daemon_request_ from `master` (asks for binding an input for a daemon). If  the *END message* is received, stop listening and wait for background bindings to stop.
2. For each daemon, open a free port (`bind-input` in background), then return its number to the `master`

*Signals:*
- If one of these signals: SIGHUP, SIGTERM, SIGINT is received, all processes, sockets and background routines will be properly (recursively) stopped.
- You **must avoid SIGKILL**, because nothing can be triggered (by definition), so all sockets and binding will remain active.


### Pool creator (master)

The `master` commands allows you to bind daemons output to another machine.

```bash
master $key $host $port $ddir
```

*Arguments:*
- `$key` is the key for the pool receiver, if it does not match, it won't work.
- `$host` is the hostname (IP addr. or resolvable) of the machine powering the `pool` receiver.
- `$port` is the number of the remote port the pool is listening on (between 1024 and 49151).
- `$ddir` is the directory containing the daemon files (must be executable).

*Execution:*
1. Send _daemon_request_ for each daemon, when open port received, start daemon in background bound to output on `$host`
2. Send the *END message*
3. Wait for daemons and output to end

*Signals:*
- If one of these signals: SIGHUP, SIGTERM, SIGINT is received, all processes, sockets and background routines will be properly (recursively) stopped.
- You **must avoid SIGKILL**, because nothing can be triggered (by definition), so all sockets and binding will remain active.




*Exemple master-pool:*

Let's say the master has 2 daemons: _dem1_ and _dem2_. Both contains a while loop echoing something each second. In this example, the key is "**k12**".

```text
                   ip:      ipM                      ip:      ipP
                   listen:  pM                       listen:  pP

                   +--------+                        +--------+
                   | master |                        |  pool  |
                   +--------+                        +--------+
                       |                                 |
               ________|________                   ______|_______
              /                 \                 /              \
             | connect to ipP:pP | =============> | listen on pP |
              \_________________/                 \______________/
                       |                                 |
                      ...                               ...
                       |                                 |
                       | ------ k12:dem1:ipM:pM -------> | bind input on free port: p1
                       |                                 |
                       |                                 |
 start dem1 to ipP:p1  | <------------- p1 ------------- |
                       |                                 |
                      ...                               ...
                       |                                 |
                       | ------ k12:dem2:ipM:pM -------> | bind input on free port: p2
                       |                                 |
                       |                                 |
 start dem2 to ipP:p2  | <------------- p2 ------------- |
                       |                                 |
                      ...                               ...
                       |                                 |
                       | --------- ENDk12END ----------> x stop listening on pP,
                       |
disconnect from ipP:pP x


                wait dem1+dem2                      wait dem1+dem2
```