anyhttp/README.md

81 lines
2.7 KiB
Markdown
Raw Normal View History

2023-09-11 21:01:20 -04:00
Create http server listening on unix sockets and systemd socket activated fds
2023-04-20 16:31:35 -04:00
## Quick Usage
2023-04-25 09:14:16 -04:00
go get go.balki.me/anyhttp
2023-04-20 16:31:35 -04:00
Just replace `http.ListenAndServe` with `anyhttp.ListenAndServe`.
```diff
- http.ListenAndServe(addr, h)
+ anyhttp.ListenAndServe(addr, h)
```
2023-04-20 17:56:44 -04:00
## Address Syntax
2023-04-20 16:31:35 -04:00
2023-04-20 17:56:44 -04:00
### Unix socket
2023-04-20 16:31:35 -04:00
Syntax
2024-12-21 16:34:12 -05:00
unix?path=<socket_path>&mode=<socket file mode>&remove_existing=<true|false>
2023-04-20 16:31:35 -04:00
Examples
2024-12-19 09:46:36 -05:00
unix?path=relative/path.sock
unix?path=/var/run/app/absolutepath.sock
2024-12-21 16:34:12 -05:00
unix?path=/run/app.sock&mode=600&remove_existing=false
2024-12-19 09:46:36 -05:00
| option | description | default |
|-----------------|------------------------------------------------|----------|
| path | path to unix socket | Required |
| mode | socket file mode | 666 |
| remove_existing | Whether to remove existing socket file or fail | true |
2023-04-20 16:31:35 -04:00
2023-04-20 17:56:44 -04:00
### Systemd Socket activated fd:
2023-04-20 16:31:35 -04:00
Syntax
2024-12-21 16:34:12 -05:00
sysd?idx=<fd index>&name=<fd name>&check_pid=<true|false>&unset_env=<true|false>&idle_timeout=<duration>
2024-12-19 09:46:36 -05:00
Only one of `idx` or `name` has to be set
2023-04-20 16:31:35 -04:00
Examples:
2024-05-09 12:10:33 -04:00
2023-04-20 16:31:35 -04:00
# First (or only) socket fd passed to app
2024-12-19 09:46:36 -05:00
sysd?idx=0
2023-04-20 16:31:35 -04:00
# Socket with FileDescriptorName
2024-12-19 09:46:36 -05:00
sysd?name=myapp
# Using default name and auto shutdown if no requests received in last 30 minutes
sysd?name=myapp.socket&idle_timeout=30m
2023-04-20 16:31:35 -04:00
2024-12-19 09:46:36 -05:00
| option | description | default |
|--------------|--------------------------------------------------------------------------------------------|------------------|
| name | Name configured via FileDescriptorName or socket file name | Required |
| idx | FD Index. Actual fd num will be 3 + idx | Required |
| idle_timeout | time to wait before shutdown. [syntax][0] | no auto shutdown |
| check_pid | Check process PID matches LISTEN_PID | true |
| unset_env | Unsets the LISTEN\* environment variables, so they don't get passed to any child processes | true |
2023-04-20 16:31:35 -04:00
2024-12-19 09:46:36 -05:00
### TCP
2023-04-20 16:31:35 -04:00
2024-12-19 09:46:36 -05:00
If the address is not one of above, it is assumed to be tcp and passed to `http.ListenAndServe`.
Examples:
2023-04-20 16:31:35 -04:00
:http
:8888
127.0.0.1:8080
2023-04-25 09:14:16 -04:00
## Documentation
https://pkg.go.dev/go.balki.me/anyhttp
### Related links
* https://gist.github.com/teknoraver/5ffacb8757330715bcbcc90e6d46ac74#file-unixhttpd-go
2023-09-11 21:01:20 -04:00
* https://github.com/coreos/go-systemd/tree/main/activation
2024-12-19 09:46:36 -05:00
[0]: https://pkg.go.dev/time#ParseDuration