From 4fcd619d0e38144d144788f165261bfbe48968f2 Mon Sep 17 00:00:00 2001
From: Dalton Hubble <dghubble@gmail.com>
Date: Fri, 30 Dec 2022 14:29:33 -0800
Subject: [PATCH] Add usage docs to the README

---
 README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 go.mod    |  2 +-
 2 files changed, 79 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1143de1..007721a 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ Package `sessions` provides minimalist Go sessions, backed by `securecookie` or
 
 ### Features
 
-* `Store` provides a predicatable interface for dealing with *individual* sessions.
+* `Store` provides an interface for managing sessions.
     * `New` returns a new named `Session`.
     * `Get` returns the named `Session` from the `http.Request` iff it was correctly verified and decoded. Otherwise the error is non-nil.
     * `Save` encodes and signs Session.Value data.
@@ -23,6 +23,83 @@ go get github.com/dghubble/sessions
 
 Read [GoDoc](https://godoc.org/github.com/dghubble/sessions)
 
+## Usage
+
+Create a `Store` for managing `Session`'s. `NewCookieStore` returns a `Store` that signs and optionally encrypts cookies to support user sessions.
+
+```go
+import (
+  "github.com/dghubble/sessions"
+)
+
+func NewServer() (http.Handler) {
+  ...
+  // client-side cookies
+  sessionProvider := sessions.NewCookieStore(
+    // use a 32 byte or 64 byte hash key
+    []byte("signing-secret"),
+    // use a 32 byte (AES-256) encryption key
+    []byte("encryption-secret")
+  )
+  sessionProvider.Config.SameSite = http.SameSiteStrictMode
+  ...
+}
+```
+
+Issue a session cookie from a handler (e.g. login handler).
+
+```go
+func (s server) Login() http.Handler {
+  fn := func(w http.ResponseWriter, req *http.Request) {
+    // create a session
+    session := s.sessions.New("my-app")
+    // add user-id to session
+    session.Values["user-id"] = 123
+    // save the session to the response
+    if err := session.Save(w); err != nil {
+      // handle error
+    }
+    ...
+  }
+  return http.HandlerFunc(fn)
+}
+```
+
+Access the session and its values (e.g. require authentication).
+
+```go
+func (s server) RequireLogin() http.Handler {
+  fn := func(w http.ResponseWriter, req *http.Request) {
+    session, err := s.sessions.Get("my-app")
+    if err != nil {
+      http.Error(w, "missing session", http.StatusUnauthorized)
+      return
+    }
+
+    userID := session.Values("user-id")
+    fmt.Fprintf(w, `<p>Welcome %d!</p>
+    <form action="/logout" method="post">
+    <input type="submit" value="Logout">
+    </form>`, userID)
+  }
+  return http.HandlerFunc(fn)
+}
+```
+
+Delete a session when a user logs out.
+
+```go
+func (s server) Logout() http.Handler {
+  fn := func(w http.ResponseWriter, req *http.Request) {
+    if req.Method == "POST" {
+      s.sessions.Destroy(w, "my-app")
+    }
+    http.Redirect(w, req, "/", http.StatusFound)
+  }
+  return http.HandlerFunc(fn)
+}
+```
+
 ### Differences from gorilla/sessions
 
 * Gorilla stores a context map of Requests to Sessions to abstract multiple sessions. `dghubble/sessions` provides individual sessions, leaving multiple sessions to a `multisessions` package. No Registry is needed.
diff --git a/go.mod b/go.mod
index cf33bf0..1d59452 100644
--- a/go.mod
+++ b/go.mod
@@ -1,5 +1,5 @@
 module github.com/dghubble/sessions
 
-go 1.18
+go 1.19
 
 require github.com/gorilla/securecookie v1.1.1