From abd0642edded01844ea85c4c0df1a2187c5dbad7 Mon Sep 17 00:00:00 2001 From: Ruidy Date: Sat, 20 Sep 2025 15:20:00 +0200 Subject: [PATCH] docs: add readme and make tooling targets --- AGENTS.md | 6 +- Makefile | 30 +++++++++ README.md | 62 +++++++++++++++++++ cmd/server/main.go | 2 +- go.mod | 2 +- internal/config/config.go | 2 +- internal/config/config_test.go | 2 +- internal/{ => driver}/logging/logging.go | 0 internal/{ => driver}/logging/logging_test.go | 0 internal/server/server.go | 2 +- 10 files changed, 100 insertions(+), 8 deletions(-) create mode 100644 Makefile create mode 100644 README.md rename internal/{ => driver}/logging/logging.go (100%) rename internal/{ => driver}/logging/logging_test.go (100%) diff --git a/AGENTS.md b/AGENTS.md index b6e2b1a..c0da58b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,9 +14,9 @@ Implement email/password authentication with secure password hashing, CSRF prote ## Build, Lint, and Test Commands -- `go run ./cmd/server` starts the dev server on . -- `go build ./...` (and `go build -o tmp/auth ./cmd/server`) validates compilation before any formatting or linting step. -- After a successful build, run `gofmt -w ./...`, `go vet ./...`, `golangci-lint run` (if configured), and `go test ./...` to keep style, static checks, and regressions in check. +- `make run` launches the server locally (defaults to ), while `make dev` hot-reloads via Air. +- `make build` compiles to `bin/auth-server`; always execute it before formatting, linting, or testing to honor the compile-first rule. +- After a clean build, run `make fmt`, `make lint`, and `make test` so every change flows through the formatter, static analyzers, and `go test ./... -cover -count=1`. ## Coding Style & Naming Conventions diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..2bba225 --- /dev/null +++ b/Makefile @@ -0,0 +1,30 @@ +BIN_DIR := bin +BIN_NAME := auth-server +FMT_PATHS := $(shell go list -f '{{.Dir}}' ./...) + +.PHONY: run dev build test fmt lint tidy clean + +run: + go run ./cmd/server + +dev: + air + +build: + @mkdir -p $(BIN_DIR) + go build -o $(BIN_DIR)/$(BIN_NAME) ./cmd/server + +test: + go test ./... -cover -count=1 + +fmt: + gofmt -w $(FMT_PATHS) + +lint: + golangci-lint run + +tidy: + go mod tidy + +clean: + rm -rf $(BIN_DIR) diff --git a/README.md b/README.md new file mode 100644 index 0000000..e85b8f4 --- /dev/null +++ b/README.md @@ -0,0 +1,62 @@ +# Auth Demo + +Auth Demo showcases a fully server-rendered email/password authentication flow +with secure session management, CSRF protection, structured logging, and embedded +templates/assets for single-binary deployment. + +## Capabilities + +- Email/password signup and login backed by salted hashing and reusable auth services. +- CSRF-protected session middleware with signed cookies and automatic token rotation. +- Structured logging (text or JSON) and environment-driven configuration for + production parity. +- Embedded templates styled with Pico.css and progressively enhanced with htmx + and Alpine.js. + +## Getting Started + +1. Review or adjust the defaults in [.env](./.env). To load them in POSIX shells, + run `set -a; . ./.env; set +a`. +2. Use the targets in the [Makefile](./Makefile): + + | Target | Description | + | ------------ | --------------------------------------------------------------------------------------- | + | `make run` | Start the HTTP server with the current environment. | + | `make dev` | Launch [Air](https://github.com/cosmtrek/air) for live reload (requires `air` on PATH). | + | `make build` | Compile to `./bin/auth-server`. | + | `make test` | Run `go test ./... -cover -count=1`. | + +3. Visit the login page (default ) and authenticate with + the demo credentials displayed on screen. + +## Configuration + +Settings are sourced from environment variables (see [.env](./.env)). + +| Variable | Required | Default | Description | +| --------------------- | -------- | ------------- | ----------------------------------------------------- | +| `AUTH_SESSION_SECRET` | Yes | — | Base64-encoded secret used to sign session cookies. | +| `AUTH_LISTEN_ADDR` | No | `:8000` | Address the HTTP server binds to. | +| `AUTH_ENV` | No | `development` | Environment label, controls logger source annotation. | +| `AUTH_LOG_MODE` | No | `text` | Structured log encoder (`text` or `json`). | + +## Project Layout + +- `cmd/server` — application entrypoint. +- `internal/config` — environment-backed configuration loader. +- `internal/driver/logging` — `slog` helpers for text/JSON output. +- `internal/service/auth` — authentication domain logic, hashing, validation. +- `internal/server` — router, middleware, handlers, session store. +- `web/templates` — embedded HTML templates. + +## Built With + +- [Go](https://go.dev/doc/) — standard library HTTP, templates, crypto, and `embed`. +- [Chi](https://github.com/go-chi/chi) — lightweight router and middleware stack. +- [htmx](https://htmx.org/) — progressive enhancement via HTML attributes. +- [Alpine.js](https://alpinejs.dev/) — declarative client-side interactions. +- [Pico.css](https://picocss.com/) — minimal, semantic-first styling. + +## License + +MIT diff --git a/cmd/server/main.go b/cmd/server/main.go index e9ceeb9..f912773 100644 --- a/cmd/server/main.go +++ b/cmd/server/main.go @@ -7,7 +7,7 @@ import ( "os" "github.com/rjnemo/auth/internal/config" - "github.com/rjnemo/auth/internal/logging" + "github.com/rjnemo/auth/internal/driver/logging" "github.com/rjnemo/auth/internal/server" ) diff --git a/go.mod b/go.mod index aacce5d..f42e4a7 100644 --- a/go.mod +++ b/go.mod @@ -2,4 +2,4 @@ module github.com/rjnemo/auth go 1.25.1 -require github.com/go-chi/chi/v5 v5.2.3 // indirect +require github.com/go-chi/chi/v5 v5.2.3 diff --git a/internal/config/config.go b/internal/config/config.go index 4110158..fb4d599 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -7,7 +7,7 @@ import ( "os" "strings" - "github.com/rjnemo/auth/internal/logging" + "github.com/rjnemo/auth/internal/driver/logging" ) const ( diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 89c7fdf..b2ba771 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -4,7 +4,7 @@ import ( "encoding/base64" "testing" - "github.com/rjnemo/auth/internal/logging" + "github.com/rjnemo/auth/internal/driver/logging" ) func TestNewDefaults(t *testing.T) { diff --git a/internal/logging/logging.go b/internal/driver/logging/logging.go similarity index 100% rename from internal/logging/logging.go rename to internal/driver/logging/logging.go diff --git a/internal/logging/logging_test.go b/internal/driver/logging/logging_test.go similarity index 100% rename from internal/logging/logging_test.go rename to internal/driver/logging/logging_test.go diff --git a/internal/server/server.go b/internal/server/server.go index 4074c2d..72c62bf 100644 --- a/internal/server/server.go +++ b/internal/server/server.go @@ -9,7 +9,7 @@ import ( "time" "github.com/rjnemo/auth/internal/config" - "github.com/rjnemo/auth/internal/logging" + "github.com/rjnemo/auth/internal/driver/logging" "github.com/rjnemo/auth/internal/service/auth" "github.com/rjnemo/auth/web" )