Email and password reset

Code

The email interface, wired in

Six files as tabs: email.go → console.go → resend.go → config.go → handlers.go → main.go (the interface + two implementations, then the config/struct/wiring that install them). The last three are modifications.

1. internal/email/email.go (new) — the Message, the Sender interface, and New (the picker: "resend" → Resend, anything else → console).

2. internal/email/console.go (new) — prints a boxed email to os.Stdout. Note the mu sync.Mutex (concurrent sends don't interleave) and the deliberate choice to write with fmt.Fprintf, not slog:

// It writes directly rather than through slog on purpose — slog would escape the
// newlines into \n literals and mangle the box.

3. internal/email/resend.go (new) — the prod sender: marshal JSON, POST https://api.resend.com/emails with a bearer token. One HTTP call.

4. internal/config/config.go (modify) — three fields: EmailSender (default "console"), ResendAPIKey, EmailFrom. Pure additions.

5. internal/handlers/handlers.go (modify) — the Handlers struct gains Mailer email.Sender; New takes it.

6. cmd/signflow/main.go (modify) — construct the sender from config and pass it in:

mailer := email.New(cfg.EmailSender, cfg.ResendAPIKey, cfg.EmailFrom, log)
h := handlers.New(cfg, queries, sessions, mailer, log)

Verify. go run ./cmd/signflow and read the very first log lines:

level=INFO msg="email: using console sender (links print to stdout, no email is sent)"

That line is the whole promise: no EMAIL_SENDER set, so you got the console sender — every email in the app will land in this terminal, no API key anywhere. Nothing sends yet (the reset handler is the next step), but the plumbing is in and announcing itself.

email.go CREATE

Create this file in internal/email/

// Package email defines an email Sender interface with two implementations: a
// console sender for development (prints the message + any links to the log, so
// registration, password reset, and signer invites all work with NO API key)
// and a Resend-backed sender for production.
package email

import (
	"context"
	"log/slog"
	"strings"
)

// Message is a single email to send.
type Message struct {
	To      string
	Subject string
	// HTML and Text are the two bodies. Text is what the console sender prints.
	HTML string
	Text string
}

// Sender delivers email. Implementations must be safe for concurrent use.
type Sender interface {
	Send(ctx context.Context, msg Message) error
}

// New picks an implementation from configuration. Anything other than "resend"
// (including the empty string) yields the console sender, so dev is zero-config.
func New(kind, apiKey, from string, log *slog.Logger) Sender {
	if strings.EqualFold(kind, "resend") {
		log.Info("email: using Resend sender", "from", from)
		return NewResendSender(apiKey, from)
	}
	log.Info("email: using console sender (links print to stdout, no email is sent)")
	return NewConsoleSender(nil)
}

console.go CREATE

Create this file in internal/email/

package email

import (
	"context"
	"fmt"
	"io"
	"os"
	"strings"
	"sync"
)

// ConsoleSender prints emails to a writer (stdout by default) instead of sending
// them. This is the default in development: a student runs the reset/invite
// flows and copies the link straight from the terminal.
//
// It writes directly rather than through slog on purpose — slog would escape the
// newlines into \n literals and mangle the box, and the whole point here is
// human readability: a student who can't read the link can't finish the lesson.
type ConsoleSender struct {
	w  io.Writer
	mu sync.Mutex // serialize writes so concurrent emails don't interleave
}

// NewConsoleSender writes to w, or os.Stdout if w is nil.
func NewConsoleSender(w io.Writer) *ConsoleSender {
	if w == nil {
		w = os.Stdout
	}
	return &ConsoleSender{w: w}
}

func (s *ConsoleSender) Send(_ context.Context, msg Message) error {
	s.mu.Lock()
	defer s.mu.Unlock()

	const bar = "──────────────────────────────────────────────────────────────"
	fmt.Fprintf(s.w, "\n┌%s\n", bar)
	fmt.Fprintf(s.w, "│ 📧  DEV EMAIL (not actually sent)\n")
	fmt.Fprintf(s.w, "│ To:      %s\n", msg.To)
	fmt.Fprintf(s.w, "│ Subject: %s\n", msg.Subject)
	fmt.Fprintf(s.w, "├%s\n", bar)
	for _, line := range strings.Split(strings.TrimRight(msg.Text, "\n"), "\n") {
		fmt.Fprintf(s.w, "│ %s\n", line)
	}
	fmt.Fprintf(s.w, "└%s\n\n", bar)
	return nil
}

resend.go CREATE

Create this file in internal/email/

package email

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

// ResendSender delivers email via the Resend HTTP API (https://resend.com).
// We hit the REST endpoint directly rather than pull in an SDK — it's one POST.
type ResendSender struct {
	apiKey string
	from   string
	client *http.Client
}

func NewResendSender(apiKey, from string) *ResendSender {
	if from == "" {
		from = "SignFlow <onboarding@resend.dev>"
	}
	return &ResendSender{
		apiKey: apiKey,
		from:   from,
		client: &http.Client{Timeout: 10 * time.Second},
	}
}

func (s *ResendSender) Send(ctx context.Context, msg Message) error {
	payload := map[string]any{
		"from":    s.from,
		"to":      []string{msg.To},
		"subject": msg.Subject,
		"html":    msg.HTML,
		"text":    msg.Text,
	}
	body, err := json.Marshal(payload)
	if err != nil {
		return err
	}

	req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.resend.com/emails", bytes.NewReader(body))
	if err != nil {
		return err
	}
	req.Header.Set("Authorization", "Bearer "+s.apiKey)
	req.Header.Set("Content-Type", "application/json")

	resp, err := s.client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	if resp.StatusCode >= 300 {
		return fmt.Errorf("resend: unexpected status %d", resp.StatusCode)
	}
	return nil
}

config.go MODIFY 8 lines changed

Edit this file in internal/config/

// Package config loads runtime configuration from the environment.
//
// In development we lean on sensible defaults so you can `go run` the app with
// zero setup. In production every value is expected to come from the
// environment (Railway injects them). The struct GROWS as the app does — the
// database URL arrives in lesson 3, the session secret in lesson 4, and so on.
package config

import (
	"fmt"
	"os"

	"github.com/joho/godotenv"
)

type Config struct {
	// DatabaseURL is a standard libpq/pgx connection string.
	DatabaseURL string
	// Port is the TCP port the HTTP server listens on. Railway sets $PORT.
	Port string
	// Env is "dev" or "prod". Later it flips cookie Secure flags and the email
	// sender; for now it is just a label.
	Env string
	// BaseURL is the public origin used to build absolute links (in emails,
	// later). In dev it is http://localhost:PORT.
	BaseURL string
	// SessionSecret authenticates the CSRF token cookie. Must be set in prod.
	SessionSecret string

	// Email configuration. EmailSender is "console" (default) or "resend".
	EmailSender  string
	ResendAPIKey string
	EmailFrom    string
}

// IsProd reports whether we are running in production. One flag, read in many
// places later (Secure cookies, strict CSRF).
func (c Config) IsProd() bool { return c.Env == "prod" }

// Load reads configuration, applying dev-friendly defaults.
func Load() (Config, error) {
	_ = godotenv.Load() // best-effort; load a local .env if present, else shrug

	cfg := Config{
		DatabaseURL:   getenv("DATABASE_URL", "postgres://postgres@localhost:5432/signflow?sslmode=disable"),
		Port:          getenv("PORT", "8080"),
		Env:           getenv("APP_ENV", "dev"),
		BaseURL:       os.Getenv("BASE_URL"),
		SessionSecret: os.Getenv("SESSION_SECRET"),
		EmailSender:   getenv("EMAIL_SENDER", "console"),
		ResendAPIKey:  os.Getenv("RESEND_API_KEY"),
		EmailFrom:     os.Getenv("EMAIL_FROM"),
	}
	if cfg.BaseURL == "" {
		cfg.BaseURL = "http://localhost:" + cfg.Port
	}

	if cfg.IsProd() && os.Getenv("BASE_URL") == "" {
		return Config{}, fmt.Errorf("BASE_URL is required in production")
	}
	if cfg.IsProd() && cfg.SessionSecret == "" {
		return Config{}, fmt.Errorf("SESSION_SECRET is required in production")
	}
	if cfg.SessionSecret == "" {
		// Dev-only fallback so CSRF works out of the box; never used in prod
		// because of the guard above.
		cfg.SessionSecret = "dev-insecure-session-secret-change-me"
	}

	return cfg, nil
}

func getenv(key, fallback string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return fallback
}

handlers.go MODIFY 5 lines changed

Edit this file in internal/handlers/

// Package handlers holds the HTTP handlers. In this skeleton there is only the
// home page and a health check; later lessons add auth, documents, and signing.
package handlers

import (
	"log/slog"
	"net/http"

	"github.com/programuoki/signflow/internal/config"
	"github.com/programuoki/signflow/internal/db"
	"github.com/programuoki/signflow/internal/email"
	"github.com/programuoki/signflow/internal/session"
	"github.com/programuoki/signflow/internal/web"
)

// Handlers bundles the dependencies every handler needs. Constructed once in
// main; its methods are registered on the router.
type Handlers struct {
	Cfg      config.Config
	Queries  *db.Queries
	Sessions *session.Manager
	Mailer   email.Sender
	Log      *slog.Logger
}

func New(cfg config.Config, q *db.Queries, sessions *session.Manager, mailer email.Sender, log *slog.Logger) *Handlers {
	return &Handlers{Cfg: cfg, Queries: q, Sessions: sessions, Mailer: mailer, Log: log}
}

// Home renders the landing page. A signed-in visitor is sent to their dashboard;
// otherwise we show the public landing page with a live user count.
func (h *Handlers) Home(w http.ResponseWriter, r *http.Request) {
	if _, ok := UserFrom(r.Context()); ok {
		http.Redirect(w, r, "/dashboard", http.StatusSeeOther)
		return
	}
	count, err := h.Queries.CountUsers(r.Context())
	if err != nil {
		h.serverError(w, r, "count users", err)
		return
	}
	render(w, r, http.StatusOK, web.Home(h.nav(r), count))
}

// Health is a liveness probe for Railway / uptime checks. It also pings the DB,
// so an unreachable database reports unhealthy rather than silently serving 500s.
func (h *Handlers) Health(w http.ResponseWriter, r *http.Request) {
	if _, err := h.Queries.CountUsers(r.Context()); err != nil {
		http.Error(w, "db unavailable", http.StatusServiceUnavailable)
		return
	}
	w.Header().Set("Content-Type", "text/plain")
	_, _ = w.Write([]byte("ok"))
}

// serverError logs the underlying error and returns a generic 500 to the client.
func (h *Handlers) serverError(w http.ResponseWriter, r *http.Request, msg string, err error) {
	h.Log.Error(msg, "err", err, "path", r.URL.Path)
	http.Error(w, "internal server error", http.StatusInternalServerError)
}

main.go MODIFY 3 lines changed

Edit this file in cmd/signflow/

// Command signflow is the HTTP server entrypoint.
//
// On startup it: loads config, runs embedded goose migrations, opens a pgx
// pool, builds the Chi router, and serves with graceful shutdown.
package main

import (
	"context"
	"crypto/sha256"
	"errors"
	"fmt"
	"io/fs"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/jackc/pgx/v5/stdlib"
	"github.com/pressly/goose/v3"

	migrations "github.com/programuoki/signflow/db"
	"github.com/programuoki/signflow/internal/config"
	"github.com/programuoki/signflow/internal/db"
	"github.com/programuoki/signflow/internal/email"
	"github.com/programuoki/signflow/internal/handlers"
	"github.com/programuoki/signflow/internal/session"
	"github.com/programuoki/signflow/static"
)

func main() {
	log := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
	if err := run(log); err != nil {
		log.Error("fatal", "err", err)
		os.Exit(1)
	}
}

func run(log *slog.Logger) error {
	cfg, err := config.Load()
	if err != nil {
		return err
	}
	log.Info("starting signflow", "env", cfg.Env, "port", cfg.Port, "base_url", cfg.BaseURL)

	ctx := context.Background()

	// 1. Migrate. We use a throwaway database/sql handle (pgx stdlib driver)
	//    because goose speaks database/sql, then hand the app a pgx pool.
	if err := runMigrations(cfg.DatabaseURL, log); err != nil {
		return err
	}

	// 2. Connect the application pool the sqlc queries run against.
	pool, err := db.Connect(ctx, cfg.DatabaseURL)
	if err != nil {
		return err
	}
	defer pool.Close()

	queries := db.New(pool)
	sessions := session.NewManager(queries, cfg.IsProd())
	mailer := email.New(cfg.EmailSender, cfg.ResendAPIKey, cfg.EmailFrom, log)
	h := handlers.New(cfg, queries, sessions, mailer, log)

	staticFS, err := fs.Sub(static.FS, "assets")
	if err != nil {
		return err
	}

	// Derive a stable 32-byte CSRF key from the session secret so there is only
	// one secret to manage.
	csrfKey := sha256.Sum256([]byte("csrf:" + cfg.SessionSecret))

	srv := &http.Server{
		Addr:              ":" + cfg.Port,
		Handler:           h.Router(staticFS, csrfKey[:]),
		ReadHeaderTimeout: 10 * time.Second,
	}

	// Graceful shutdown: stop accepting on SIGINT/SIGTERM, then drain in-flight
	// requests for up to 15s before exiting.
	shutdownCtx, stop := signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)
	defer stop()

	go func() {
		log.Info("listening", "addr", srv.Addr)
		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
			log.Error("server error", "err", err)
			stop()
		}
	}()

	<-shutdownCtx.Done()
	log.Info("shutting down")

	timeout, cancel := context.WithTimeout(context.Background(), 15*time.Second)
	defer cancel()
	return srv.Shutdown(timeout)
}

// runMigrations applies all pending goose migrations from the embedded FS.
func runMigrations(databaseURL string, log *slog.Logger) error {
	sqlDB, err := goose.OpenDBWithDriver("pgx", databaseURL)
	if err != nil {
		return err
	}
	defer sqlDB.Close()

	goose.SetBaseFS(migrations.FS)
	goose.SetLogger(gooseLogger{log})
	if err := goose.SetDialect("postgres"); err != nil {
		return err
	}
	return goose.Up(sqlDB, "migrations")
}

// gooseLogger adapts slog to goose's logger interface.
type gooseLogger struct{ log *slog.Logger }

func (g gooseLogger) Fatalf(format string, v ...interface{}) {
	g.log.Error("goose", "msg", fmt.Sprintf(format, v...))
}
func (g gooseLogger) Printf(format string, v ...interface{}) {
	g.log.Info("goose", "msg", fmt.Sprintf(format, v...))
}

// ensure the pgx stdlib driver is registered for goose.OpenDBWithDriver("pgx", ...)
var _ = stdlib.GetDefaultDriver