Documentation
¶
Overview ¶
Package cookie provides HTTP cookie management with optional signing and encryption.
The Manager handles plain, signed, and encrypted cookies, plus flash messages. Secrets are optional; encrypted and signed operations return ErrNoSecret without one.
Basic Usage ¶
Plain cookies work without a secret:
import (
"net/http"
"github.com/dmitrymomot/forge/pkg/cookie"
)
func handler(w http.ResponseWriter, r *http.Request) {
m, _ := cookie.New(cookie.Config{})
m.Set(w, "theme", "dark", 86400)
value, err := m.Get(r, "theme")
if err != nil {
// handle error
}
}
With Secret ¶
Enable signing and encryption with a 32+ byte secret:
m, err := cookie.New(cookie.Config{
Secret: "your-32+-byte-secret-key-here!!",
Secure: true,
HTTPOnly: true,
})
Signed cookies detect tampering with HMAC-SHA256:
err := m.SetSigned(w, "session", sessionID, 86400) value, err := m.GetSigned(r, "session")
Encrypted cookies use AES-256-GCM:
err := m.SetEncrypted(w, "prefs", userPrefs, 86400) value, err := m.GetEncrypted(r, "prefs")
Flash Messages ¶
Flash messages are encrypted, single-read values that auto-delete after reading. They are useful for displaying success/error messages after redirects:
// Set a flash message
m.SetFlash(w, "msg", map[string]string{"type": "success", "text": "Saved!"})
// Read and delete in the same request
var msg map[string]string
err := m.Flash(w, r, "msg", &msg)
// Flash is now deleted (no further reads will return it)
Configuration ¶
Use Config to configure cookie attributes:
- Secret: Set the secret for signing/encryption (32+ bytes)
- Domain: Set the cookie domain
- Path: Set the cookie path (default: "/")
- SameSite: Set the SameSite attribute as string (default: "lax")
- Secure: Set the Secure flag (HTTPS only)
- HTTPOnly: Set the HttpOnly flag (default: false)
Errors ¶
The package defines these sentinel errors:
- ErrNotFound: Cookie does not exist
- ErrNoSecret: Secret required for signed/encrypted operations
- ErrBadSecret: Secret must be at least 32 bytes
- ErrBadSig: Signature verification failed (tampering detected)
- ErrDecrypt: Decryption failed (tampering or corruption detected)
Index ¶
- Variables
- type Config
- type Manager
- func (m *Manager) Delete(w http.ResponseWriter, name string)
- func (m *Manager) Flash(w http.ResponseWriter, r *http.Request, key string, dest any) error
- func (m *Manager) Get(r *http.Request, name string) (string, error)
- func (m *Manager) GetEncrypted(r *http.Request, name string) (string, error)
- func (m *Manager) GetSigned(r *http.Request, name string) (string, error)
- func (m *Manager) Set(w http.ResponseWriter, name, value string, maxAge int)
- func (m *Manager) SetEncrypted(w http.ResponseWriter, name, value string, maxAge int) error
- func (m *Manager) SetFlash(w http.ResponseWriter, key string, value any) error
- func (m *Manager) SetSigned(w http.ResponseWriter, name, value string, maxAge int) error
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotFound = errors.New("cookie: not found") ErrNoSecret = errors.New("cookie: secret required") ErrBadSecret = errors.New("cookie: secret must be 32+ bytes") ErrBadSig = errors.New("cookie: invalid signature") ErrDecrypt = errors.New("cookie: decryption failed") )
Errors.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Secret string `env:"SECRET"`
Domain string `env:"DOMAIN"`
Path string `env:"PATH" envDefault:"/"`
SameSite string `env:"SAME_SITE" envDefault:"lax"`
Secure bool `env:"SECURE" envDefault:"false"`
HTTPOnly bool `env:"HTTP_ONLY" envDefault:"true"`
}
Config configures the cookie Manager.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager handles cookie operations.
func New ¶
New creates a cookie Manager with the given config. Returns ErrBadSecret if Secret is non-empty but shorter than 32 bytes.
func (*Manager) Delete ¶
func (m *Manager) Delete(w http.ResponseWriter, name string)
Delete removes a cookie.
func (*Manager) Flash ¶
Flash reads and deletes a flash message. Returns ErrNoSecret if no secret is configured. Returns ErrNotFound if the flash cookie doesn't exist.
func (*Manager) GetEncrypted ¶
GetEncrypted returns an encrypted cookie value. Returns ErrNoSecret if no secret is configured. Returns ErrDecrypt if decryption fails.
func (*Manager) GetSigned ¶
GetSigned returns a signed cookie value. Returns ErrNoSecret if no secret is configured. Returns ErrBadSig if signature verification fails.
func (*Manager) Set ¶
func (m *Manager) Set(w http.ResponseWriter, name, value string, maxAge int)
Set sets a plain cookie.
func (*Manager) SetEncrypted ¶
SetEncrypted sets an encrypted cookie. Returns ErrNoSecret if no secret is configured.
Source Files