balki/anyhttp
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
Balakrishnan Balasubramanian 2024-12-19 09:46:36 -05:00
parent 06e51af628
commit 74efe7c808
1 changed files with 31 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
README.md
View File

@ -17,56 +17,57 @@ Just replace `http.ListenAndServe` with `anyhttp.ListenAndServe`.
Syntax
unix/<path to socket>
unix?path=<socket_path>&mode=<socket file mode>&remove_existing=<yes|no>
Examples
unix/relative/path.sock
unix//var/run/app/absolutepath.sock
unix?path=relative/path.sock
unix?path=/var/run/app/absolutepath.sock
unix?path=/run/app.sock&mode=600&remove_existing=no
| 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 |
### Systemd Socket activated fd:
Syntax
sysd/fdidx/<fd index starting at 0>
sysd/fdname/<fd name set using FileDescriptorName socket setting >
sysd?idx=<fd index>&name=<fd name>&check_pid=<yes|no>&unset_env=<yes|no>&idle_timeout=<duration>
Only one of `idx` or `name` has to be set
Examples:
# First (or only) socket fd passed to app
sysd/fdidx/0
sysd?idx=0
# Socket with FileDescriptorName
sysd/fdname/myapp
sysd?name=myapp
# Using default name
sysd/fdname/myapp.socket
# Using default name and auto shutdown if no requests received in last 30 minutes
sysd?name=myapp.socket&idle_timeout=30m
### TCP port
| 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 |
If the address is a number less than 65536, it is assumed as a port and passed
as `http.ListenAndServe(":<port>",...)` Anything else is directly passed to
`http.ListenAndServe` as well. Below examples should work
### TCP
If the address is not one of above, it is assumed to be tcp and passed to `http.ListenAndServe`.
Examples:
:http
:8888
127.0.0.1:8080
## Idle server auto shutdown
When using systemd socket activation, idle servers can be shut down to save on
resources. They will be restarted with socket activation when new request
arrives. Quick example for the case. (Error checking skipped for brevity)
```go
addrType, httpServer, done, _ := anyhttp.Serve(addr, idle.WrapHandler(nil))
if addrType == anyhttp.SystemdFD {
idle.Wait(30 * time.Minute)
httpServer.Shutdown(context.TODO())
}
<-done
```
## Documentation
https://pkg.go.dev/go.balki.me/anyhttp
@ -75,3 +76,5 @@ https://pkg.go.dev/go.balki.me/anyhttp
* https://gist.github.com/teknoraver/5ffacb8757330715bcbcc90e6d46ac74#file-unixhttpd-go
* https://github.com/coreos/go-systemd/tree/main/activation
[0]: https://pkg.go.dev/time#ParseDuration