.github/workflows/ci.yml

@@ -1,4 +1,13 @@
-on: [push, pull_request]
+on:
+  push:
+    branches: '**'
+    paths-ignore:
+      - 'docs/**'
+  pull_request:
+    branches: '**'
+    paths-ignore:
+      - 'docs/**'
+
 name: Test
 jobs:
   test:
@@ -12,7 +21,7 @@ jobs:
 
     strategy:
       matrix:
-        go-version: [1.14.x, 1.15.x, 1.16.x]
+        go-version: [1.14.x, 1.15.x, 1.16.x, 1.17.x]
         os: [ubuntu-latest, macos-latest, windows-latest]
 
     runs-on: ${{ matrix.os }}

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v5.0.4 (2021-08-29)
+
+- History of changes: see https://github.com/go-chi/chi/compare/v5.0.3...v5.0.4
+
+
 ## v5.0.3 (2021-04-29)
 
 - History of changes: see https://github.com/go-chi/chi/compare/v5.0.2...v5.0.3

Makefile

@@ -12,3 +12,7 @@ test-router:
 
 test-middleware:
 	go test -race -v ./middleware
+
+.PHONY: docs
+docs:
+	npx docsify-cli serve ./docs

_examples/graceful/main.go

@@ -3,58 +3,61 @@ package main
 import (
 	"context"
 	"fmt"
-	"net"
+	"log"
 	"net/http"
 	"os"
 	"os/signal"
+	"syscall"
 	"time"
 
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
-	"github.com/go-chi/valve"
 )
 
 func main() {
+	// The HTTP Server
+	server := &http.Server{Addr: "0.0.0.0:3333", Handler: service()}
 
-	// Our graceful valve shut-off package to manage code preemption and
-	// shutdown signaling.
-	valv := valve.New()
-	baseCtx := valv.Context()
-
-	// Example of a long running background worker thing..
-	go func(ctx context.Context) {
-		for {
-			<-time.After(1 * time.Second)
-
-			func() {
-				valve.Lever(ctx).Open()
-				defer valve.Lever(ctx).Close()
-
-				// actual code doing stuff..
-				fmt.Println("tick..")
-				time.Sleep(2 * time.Second)
-				// end-logic
-
-				// signal control..
-				select {
-				case <-valve.Lever(ctx).Stop():
-					fmt.Println("valve is closed")
-					return
-
-				case <-ctx.Done():
-					fmt.Println("context is cancelled, go home.")
-					return
-				default:
-				}
-			}()
+	// Server run context
+	serverCtx, serverStopCtx := context.WithCancel(context.Background())
 
+	// Listen for syscall signals for process to interrupt/quit
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, syscall.SIGHUP, syscall.SIGINT, syscall.SIGTERM, syscall.SIGQUIT)
+	go func() {
+		<-sig
+
+		// Shutdown signal with grace period of 30 seconds
+		shutdownCtx, _ := context.WithTimeout(serverCtx, 30*time.Second)
+
+		go func() {
+			<-shutdownCtx.Done()
+			if shutdownCtx.Err() == context.DeadlineExceeded {
+				log.Fatal("graceful shutdown timed out.. forcing exit.")
+			}
+		}()
+
+		// Trigger graceful shutdown
+		err := server.Shutdown(shutdownCtx)
+		if err != nil {
+			log.Fatal(err)
 		}
-	}(baseCtx)
+		serverStopCtx()
+	}()
 
-	// HTTP service running in this program as well. The valve context is set
-	// as a base context on the server listener at the point where we instantiate
-	// the server - look lower.
+	// Run the server
+	err := server.ListenAndServe()
+	if err != nil && err != http.ErrServerClosed {
+		log.Fatal(err)
+	}
+
+	// Wait for server context to be stopped
+	<-serverCtx.Done()
+}
+
+func service() http.Handler {
 	r := chi.NewRouter()
+
 	r.Use(middleware.RequestID)
 	r.Use(middleware.Logger)
 
@@ -63,57 +66,17 @@ func main() {
 	})
 
 	r.Get("/slow", func(w http.ResponseWriter, r *http.Request) {
-
-		valve.Lever(r.Context()).Open()
-		defer valve.Lever(r.Context()).Close()
-
-		select {
-		case <-valve.Lever(r.Context()).Stop():
-			fmt.Println("valve is closed. finish up..")
-
-		case <-time.After(5 * time.Second):
-			// The above channel simulates some hard work.
-			// We want this handler to complete successfully during a shutdown signal,
-			// so consider the work here as some background routine to fetch a long running
-			// search query to find as many results as possible, but, instead we cut it short
-			// and respond with what we have so far. How a shutdown is handled is entirely
-			// up to the developer, as some code blocks are preemptable, and others are not.
-			time.Sleep(5 * time.Second)
-		}
+		// Simulates some hard work.
+		//
+		// We want this handler to complete successfully during a shutdown signal,
+		// so consider the work here as some background routine to fetch a long running
+		// search query to find as many results as possible, but, instead we cut it short
+		// and respond with what we have so far. How a shutdown is handled is entirely
+		// up to the developer, as some code blocks are preemptable, and others are not.
+		time.Sleep(5 * time.Second)
 
 		w.Write([]byte(fmt.Sprintf("all done.\n")))
 	})
 
-	srv := http.Server{Addr: ":3333", Handler: r}
-	srv.BaseContext = func(_ net.Listener) context.Context {
-		return baseCtx
-	}
-
-	c := make(chan os.Signal, 1)
-	signal.Notify(c, os.Interrupt)
-	go func() {
-		for range c {
-			// sig is a ^C, handle it
-			fmt.Println("shutting down..")
-
-			// first valv
-			valv.Shutdown(20 * time.Second)
-
-			// create context with timeout
-			ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
-			defer cancel()
-
-			// start http shutdown
-			srv.Shutdown(ctx)
-
-			// verify, in worst case call cancel via defer
-			select {
-			case <-time.After(21 * time.Second):
-				fmt.Println("not all connections done")
-			case <-ctx.Done():
-
-			}
-		}
-	}()
-	srv.ListenAndServe()
+	return r
 }

_examples/todos-resource/users.go

@@ -13,36 +13,36 @@ func (rs usersResource) Routes() chi.Router {
 	r := chi.NewRouter()
 	// r.Use() // some middleware..
 
-	r.Get("/", rs.List)    // GET /todos - read a list of todos
-	r.Post("/", rs.Create) // POST /todos - create a new todo and persist it
+	r.Get("/", rs.List)    // GET /users - read a list of users
+	r.Post("/", rs.Create) // POST /users - create a new user and persist it
 	r.Put("/", rs.Delete)
 
 	r.Route("/{id}", func(r chi.Router) {
-		// r.Use(rs.TodoCtx) // lets have a todos map, and lets actually load/manipulate
-		r.Get("/", rs.Get)       // GET /todos/{id} - read a single todo by :id
-		r.Put("/", rs.Update)    // PUT /todos/{id} - update a single todo by :id
-		r.Delete("/", rs.Delete) // DELETE /todos/{id} - delete a single todo by :id
+		// r.Use(rs.TodoCtx) // lets have a users map, and lets actually load/manipulate
+		r.Get("/", rs.Get)       // GET /users/{id} - read a single user by :id
+		r.Put("/", rs.Update)    // PUT /users/{id} - update a single user by :id
+		r.Delete("/", rs.Delete) // DELETE /users/{id} - delete a single user by :id
 	})
 
 	return r
 }
 
 func (rs usersResource) List(w http.ResponseWriter, r *http.Request) {
-	w.Write([]byte("aaa list of stuff.."))
+	w.Write([]byte("users list of stuff.."))
 }
 
 func (rs usersResource) Create(w http.ResponseWriter, r *http.Request) {
-	w.Write([]byte("aaa create"))
+	w.Write([]byte("users create"))
 }
 
 func (rs usersResource) Get(w http.ResponseWriter, r *http.Request) {
-	w.Write([]byte("aaa get"))
+	w.Write([]byte("user get"))
 }
 
 func (rs usersResource) Update(w http.ResponseWriter, r *http.Request) {
-	w.Write([]byte("aaa update"))
+	w.Write([]byte("user update"))
 }
 
 func (rs usersResource) Delete(w http.ResponseWriter, r *http.Request) {
-	w.Write([]byte("aaa delete"))
+	w.Write([]byte("user delete"))
 }

docs/CNAME

@@ -0,0 +1 @@
+go-chi.io

docs/README.md

@@ -0,0 +1,50 @@
+# chi
+
+## 👋 Hi, Let's Get You Started With chi <!-- {docsify-ignore} -->
+
+<!-- # chi -->
+
+`chi` is a lightweight, idiomatic and composable router for building Go HTTP services. It's
+especially good at helping you write large REST API services that are kept maintainable as your
+project grows and changes. `chi` is built on the new `context` package introduced in Go 1.7 to
+handle signaling, cancelation and request-scoped values across a handler chain.
+
+The focus of the project has been to seek out an elegant and comfortable design for writing
+REST API servers, written during the development of the Pressly API service that powers our
+public API service, which in turn powers all of our client-side applications.
+
+The key considerations of chi's design are: project structure, maintainability, standard http
+handlers (stdlib-only), developer productivity, and deconstructing a large system into many small
+parts. The core router `github.com/go-chi/chi` is quite small (less than 1000 LOC), but we've also
+included some useful/optional subpackages: [middleware](https://github.com/go-chi/chi/tree/master/middleware), [render](https://github.com/go-chi/render)
+and [docgen](https://github.com/go-chi/docgen). We hope you enjoy it too!
+
+## Features <!-- {docsify-ignore} -->
+
+* **Lightweight** - cloc'd in ~1000 LOC for the chi router
+* **Fast** - yes, see [benchmarks](https://github.com/go-chi/chi#benchmarks)
+* **100% compatible with net/http** - use any http or middleware pkg in the ecosystem that is also compatible with `net/http`
+* **Designed for modular/composable APIs** - middlewares, inline middlewares, route groups and sub-router mounting
+* **Context control** - built on new `context` package, providing value chaining, cancellations and timeouts
+* **Robust** - in production at Pressly, CloudFlare, Heroku, 99Designs, and many others (see [discussion](https://github.com/go-chi/chi/issues/91))
+* **Doc generation** - `docgen` auto-generates routing documentation from your source to JSON or Markdown
+* **Go.mod support** - as of v5, go.mod support (see [CHANGELOG](https://github.com/go-chi/chi/blob/master/CHANGELOG.md))
+* **No external dependencies** - plain ol' Go stdlib + net/http
+
+
+
+## Examples <!-- {docsify-ignore} -->
+
+See [examples](https://github.com/go-chi/chi/blob/master/_examples/) for a variety of examples.
+
+
+## License <!-- {docsify-ignore} -->
+
+Copyright (c) 2015-present [Peter Kieltyka](https://github.com/pkieltyka)
+
+Licensed under [MIT License](https://github.com/go-chi/chi/blob/master/LICENSE)
+
+[GoDoc]: https://pkg.go.dev/github.com/go-chi/chi?tab=versions
+[GoDoc Widget]: https://godoc.org/github.com/go-chi/chi?status.svg
+[Travis]: https://travis-ci.org/go-chi/chi
+[Travis Widget]: https://travis-ci.org/go-chi/chi.svg?branch=master

docs/_coverpage.md

@@ -0,0 +1,17 @@
+![logo](https://cdn.rawgit.com/go-chi/chi/master/_examples/chi.svg)
+
+> A lightweight, idiomatic and composable router for building Go HTTP services.
+
+- 🚀 Lightweight
+- ⚡️️ Fast
+- 🔥 Robust
+- 📼 No external dependencies
+
+<div class="buttons">
+  <a href="https://github.com/go-chi/chi/" target="_blank"><span>GitHub</span></a>
+  <a href="#/README"><span>Get Started</span></a>
+</div>
+
+<!-- background color -->
+
+![color](#000000)

docs/_sidebar.md

@@ -0,0 +1,22 @@
+<!-- docs/_sidebar.md -->
+<!-- - [🏃‍♂️ Quick Start Tutorial](quickstart.md) -->
+<!-- - Tutorial - User Guide
+    - [First Steps]()
+    - [Routing Basics]()
+    - [Routing Patterns & URL Params]()
+    - [Mounting Routers and Sub Routers]()
+    - [Middleware]() -->
+<!-- docs/advanced_user_guide/_sidebar.md -->
+- [👋 Introduction](README.md)
+- [⚡ Getting Started](user_guide/first_steps.md)
+- [🔌 Routing](user_guide/routing.md)
+- [🧬 Middleware](user_guide/middleware.md)
+- [🧪 Testing](user_guide/testing.md)
+- [🍳 Examples](https://github.com/go-chi/chi/tree/master/_examples)
+- [⚖️ License](https://github.com/go-chi/chi/blob/master/LICENSE)
+<!-- - [📚 User Guide](user_guide/index.md)
+    - [👋 First Steps](user_guide/first_steps.md)
+    - [🔌 Routing](user_guide/routing.md)
+    - [🧬 Middleware](user_guide/middleware.md)
+    - [🧪 Testing](user_guide/testing.md)
+    - [🍳 Examples](https://github.com/go-chi/chi/tree/master/_examples) -->