This is a small CLI tool for unix-likes that creates a TCP socket at the address you tell it to, then passes its FD index to a child process using an environment variable. The child (or any descendants) can then bind the socket.
The idea is for tools that reload servers, for instance cargo watch:
$ catflap cargo watch [Catflap listening at 127.0.0.1:5000] [Running 'cargo run'] Compiling sample-server v0.1.0 (file:///home/code/rust/test) Finished dev [unoptimized + debuginfo] target(s) in 0.71 secs Running `target/debug/sample-server` Binding to socket FD 3 Serving requests... [[ Some file is changed so the server is reloaded ]] [Running 'cargo run'] Compiling sample-server v0.1.0 (file:///home/code/rust/test) Finished dev [unoptimized + debuginfo] target(s) in 0.84 secs Running `target/debug/sample-server` Binding to socket FD 3 Serving requests... [[ etc ]]
Servers that bind to ports might encounter EADDRINUSE and similar errors, as they attempt to listen on the same address but before the OS has freed them. Additionally, because the socket is always bound, requests simply wait for the program to answer them instead of failing when the server is restarting, leading to a better development experience.
Often, process supervisors implement this functionality, for example systemd, lithos, or the Flask dev server. Catflap is a single-purpose tool that does this and only this, so it can be used without all the configuration or dependence on a particular framework, and it can thus be plugged into your development workspace at very little cost.
The usual way:
$ cargo install catflap
Or, to upgrade:
$ cargo install --force catflap
$ catflap [options] [--] <command> [args...] $ catflap -e LISTEN_FDS -- <command> [args...] $ catflap -h 0.0.0.0 [--] <command> [args...] $ catflap -p 8000 [--] <command> [args...]
||Environment variable that will hold the socket's FD.|
||IP address (IPv4 or IPv6, no domain names) to bind the socket to.|
||Port to bind the socket to.|
<command> is executed directly, without passing through a shell, so
shellisms cannot be used directly. Additionally, you'll want to use
separate catflap options from program options:
$ catflap 'foo && bar' # Will error because 'foo && bar' doesn't exist in PATH $ catflap sh -c 'foo && bar' # Will error because '-c' is not a catflap option $ catflap -- sh -c 'foo && bar' # Will work!
If you specify port zero, the system will pick an unused high port at random. Catflap prints the socket's actual address right before it execs the given command, so you can find the right port to connect to.
$ catflap -p 0 cargo watch [Catflap listening at 127.0.0.1:55917]
These can be built and run directly in the respective folder.
$ curl -i http://localhost:5000.
The name is both because it's a small door that you install so that you don't
have to constantly open and close and open and close a bigger door for your
furry companion, and as a play on the