{"id":16980055,"url":"https://github.com/aoliveti/gracefulhttp","last_synced_at":"2025-04-12T01:43:24.920Z","repository":{"id":226825416,"uuid":"768858788","full_name":"aoliveti/gracefulhttp","owner":"aoliveti","description":"A Go library for graceful shutdown of an HTTP server, configured using best practices.","archived":false,"fork":false,"pushed_at":"2025-01-29T15:16:35.000Z","size":37,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T21:23:01.456Z","etag":null,"topics":["cloudflare","go","graceful","graceful-shutdown","http","http-server","https","shutdown"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aoliveti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-07T21:37:19.000Z","updated_at":"2025-01-29T14:56:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"98eaf2a4-dc98-4972-9934-577269c2ae8b","html_url":"https://github.com/aoliveti/gracefulhttp","commit_stats":null,"previous_names":["aoliveti/gracefulhttp"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoliveti%2Fgracefulhttp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoliveti%2Fgracefulhttp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoliveti%2Fgracefulhttp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoliveti%2Fgracefulhttp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aoliveti","download_url":"https://codeload.github.com/aoliveti/gracefulhttp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248505869,"owners_count":21115353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","go","graceful","graceful-shutdown","http","http-server","https","shutdown"],"created_at":"2024-10-14T01:49:01.745Z","updated_at":"2025-04-12T01:43:24.900Z","avatar_url":"https://github.com/aoliveti.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## gracefulhttp\n![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/aoliveti/gracefulhttp)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/aoliveti/gracefulhttp/go.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/aoliveti/curling)](https://pkg.go.dev/github.com/aoliveti/gracefulhttp)\n[![codecov](https://codecov.io/gh/aoliveti/gracefulhttp/graph/badge.svg?token=j9a2QoWNA5)](https://codecov.io/gh/aoliveti/gracefulhttp)\n[![Go Report Card](https://goreportcard.com/badge/github.com/aoliveti/gracefulhttp)](https://goreportcard.com/report/github.com/aoliveti/gracefulhttp)\n![GitHub License](https://img.shields.io/github/license/aoliveti/gracefulhttp)\n\nThis package extends the functionality of the standard [http.Server](https://pkg.go.dev/net/http#Server) in Go to include best practice configurations and graceful shutdown.\n\n- Smoothly stop accepting new connections while processing existing requests to completion.\n- Set a customizable timeout for graceful shutdown, with a default of 5 seconds.\n- Forcibly close ongoing connections after the timeout expires.\n- Support graceful shutdown for HTTP and HTTPS servers.\n- **Apply best practice configurations** inspired by Cloudflare for timeout management and TLS setup ([Read more](https://blog.cloudflare.com/exposing-go-on-the-internet/)).\n\n## Installation\n```bash\ngo get github.com/aoliveti/gracefulhttp\n```\n\n## Usage\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"net/http\"\n\t\"os/signal\"\n\n\t\"github.com/aoliveti/gracefulhttp\"\n\t\"golang.org/x/sys/unix\"\n)\n\nfunc main() {\n\tctx, cancel := signal.NotifyContext(context.Background(), unix.SIGINT, unix.SIGTERM)\n\tdefer cancel()\n\n\thttp.HandleFunc(\"/\", func(w http.ResponseWriter, r *http.Request) {\n\t\t_, _ = w.Write([]byte(\"Hello world!\"))\n\t})\n\n\tsrv := gracefulhttp.Bind(\":8080\", nil)\n\n\tlog.Println(\"starting server...\")\n\n\tif err := srv.ListenAndServeWithShutdown(ctx); err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tlog.Println(\"graceful shutdown completed successfully\")\n}\n```\nYou can instantiate a GracefulServer in two different ways:\n```go\ngracefulhttp.GracefulServer{\n    Server: http.Server{\n        Addr:    \":8080\",\n        Handler: nil,\n    },\n}\n```\nor by using the Bind() function:\n```go\nfunc Bind(addr string, handler http.Handler) *GracefulServer\n```\n\n## Listen and serve\nTo start the HTTP server with the provided address and handler, you need to use this function:\n```go\nfunc (s *GracefulServer) ListenAndServeWithShutdown(ctx context.Context, opts ...GracefulServerOption) error\n```\nIf instead you need to start a server that accepts connections over HTTPS, you must ensure to provide files containing a certificate and matching private key for the server. You should use this function:\n```go\nfunc (s *GracefulServer) ListenAndServeTLSWithShutdown(ctx context.Context, certFile string, keyFile string, opts ...GracefulServerOption) error\n```\nIt's possible to pass options to set timeouts and [TLS configuration](https://pkg.go.dev/crypto/tls#Config). Here's a summary table:\n\n| Option                  | Description                                                                                                       |\n|-------------------------|-------------------------------------------------------------------------------------------------------------------|\n| WithShutdownTimer       | Sets the timeout for a graceful shutdown, after which all active connections will be forcibly closed              |\n| WithCloudflareTimeouts  | Applies timeout patches to the server, implementing best practice configurations inspired by Cloudflare           |\n| WithCloudflareTLSConfig | Applies TLS configuration patches to the server, implementing best practice configurations inspired by Cloudflare |\n| WithTLSConfig           | Sets the provided TLS configuration                                                                               |\n\n## Build and Test\n\n### Building the Project\n\nYou can build the project using the provided [Makefile](Makefile). Simply run:\n\n```sh\nmake\n```\n\n### Running Tests\n\nTo run tests, use the following command:\n\n```sh\nmake test\n```\n\nBefore running the tests, a certificate and key are generated using OpenSSL and placed in the `certs` directory.\nThe generated certificate and key are used for testing HTTPS functions.\n\nFor detailed documentation on OpenSSL, visit https://www.openssl.org/\n\n## License\n\nThe library is released under the MIT license. See [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faoliveti%2Fgracefulhttp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faoliveti%2Fgracefulhttp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faoliveti%2Fgracefulhttp/lists"}