diff --git a/README.md b/README.md new file mode 100644 index 0000000..c43e33e --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +# ipcsockd + +ipcsockd (**i**nter-**p**rocess **c**ommunication **sock**et **d**aemon) is a +super-server daemon for UNIX domain sockets. Think of it as `xinetd` but for +UNIX domain sockets. + +## Examples + +To run a command `myserver http` everytime a connection to the socket `a.sock` +in the current directory is made: + +``` +ipcsockd ./a.sock myserver http +``` + +For each incoming connection, `ipcsockd` will execute the command `myserver +http` in a separate thread, with passing input from the socket to the thread's +stdin, and passing output from the thread's stdout back to the socket. + +To run a command with flags (ex. `myserver http --cool-feature -v`), prepend +the command with a `--` to escape those arguments: + +``` +ipcsockd ./a.sock -- myserver http --cool-feature -v +``` + +If `--` is not provided, `ipcsockd` will assume those flags were meant for +itself rather than for the command. + +To perform the same given above, but limit concurrent connections to 20: + +``` +ipcsockd -l 20 ./a.sock -- myserver http --cool-feature -v +``` +`ipcsockd` is not limited to just HTTP applications. You can do much more with +it. + +For more technical information, run `ipcsockd --help`. + +### Real demo + +This demo requires `ncat` (`nc`) to be installed. + +Here, we create a socket `/tmp/cat.sock` which echoes what you send to the +socket back. Bind to the socket using `ipcsockd` and instruct it to run +`cat(1)` for each connection. + +``` +ipcsockd /tmp/cat.sock cat +``` + +It should print "OK". Now, in another terminal, run + +``` +echo "hello" | nc -U /tmp/cat.sock +``` + +It will print "hello" back! + +``` +$ echo "hello" | nc -U /tmp/cat.sock +hello +``` + +You can also try this using `curl(1)`: + +``` +$ curl --unix-socket /tmp/cat.sock http://localhost/hello --http0.9 +GET /hello HTTP/1.1 +Host: localhost +User-Agent: curl/7.82.0 +Accept: */* +``` + +It printed the request curl sent to the socket. + +## Install + +ipcsockd requires a Rust toolchain installed. To build a debug build (ideal for +testing/reporting bugs), run + +``` +cargo build +``` + +For a release build (no debug information, ideal to distribute or run in +production), run + +``` +cargo build --release +``` + +## Relevant/similar work + +- [s6-ipcserver](https://skarnet.org/software/s6/s6-ipcserver.html) + +## Copyright and license notices + +Copyright (C) 2022 Pranav Karawale + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU Affero General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Affero General Public License for more details. + +You should have received a copy of the GNU Affero General Public License +along with this program. If not, see . + +This notice and license notices of dependencies can be found in the `LICENSE` +file. + diff --git a/build.rs b/build.rs deleted file mode 100644 index 4997de6..0000000 --- a/build.rs +++ /dev/null @@ -1,18 +0,0 @@ -use clap_mangen::Man; - -include!("src/cli.rs"); - -fn main() -> std::io::Result<()> { - let out_dir = std::path::PathBuf::from( - std::env::var_os("OUT_DIR").ok_or_else(|| std::io::ErrorKind::NotFound)?, - ); - - let cmd = Cli::command(); - let man = Man::new(cmd); - let mut buffer: Vec = Default::default(); - man.render(&mut buffer)?; - - std::fs::write(out_dir.join("ipcsockd.1"), buffer)?; - - Ok(()) -} diff --git a/src/cli.rs b/src/cli.rs index 74d5240..0325b91 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -1,3 +1,7 @@ +// SPDX-FileCopyrightText: 2022 Pranav Karawale +// +// SPDX-License-Identifier: AGPL-3.0-or-later + #[allow(unused_imports)] use clap::{CommandFactory, Parser}; @@ -16,13 +20,14 @@ use clap::{CommandFactory, Parser}; /// Here, the arguments --arg1 and --arg2 are passed to mycommand during the time /// of execution instead of being parsed by ipcsockd. /// +/// WARNING: ipcsockd will remove the socket if it already exists. +/// /// ipcsockd prints a message "OK" to standard error when it is ready to receive /// requests. This can be utilised to check the status of the server. /// /// ipcsockd limits the maximum amount of concurrent requests at a particular point /// in time, which can be configured using flags. Advanced rate-limiting and similar /// utilities are left to be handled by a reverse proxy. - #[derive(Parser, Debug)] #[command(author, version, about, verbatim_doc_comment)] pub struct Cli {