File upload and SHA-256 in one pass

Code

The storage layer and the documents table

Seven files as tabs, bottom-up: the storage layer, then the table, then the wiring. storage.go → local.go → 00004_documents.sql → documents.sql → config.go → handlers.go → main.go.

1. internal/storage/storage.go (new) — the Store interface. Three methods, and the package comment names the seam out loud: it is the same pattern as email.Sender, and it is here because Railway's container filesystem is ephemeral.

2. internal/storage/local.go (new) — LocalStore. The heart is Save: open the file, then io.Copy(io.MultiWriter(f, h), r) — one pass, hash and write together. On any copy or close error it removes the half-written file so a failed upload leaves nothing behind. Open/Delete run the key through safePath, which enforces keyPattern before joining it to the base dir. newKey is 16 random bytes as hex.

3. db/migrations/00004_documents.sql (new) — the documents table:

owner_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
file_hash    TEXT NOT NULL,                 -- SHA-256, hex
storage_key  TEXT NOT NULL,                 -- opaque key into the store
status       TEXT NOT NULL DEFAULT 'draft'
             CHECK (status IN ('draft', 'sent', 'completed')),

status is TEXT + CHECK, not a Postgres ENUM — the set is small and fixed, and extending a check constraint later beats an ALTER TYPE dance. The lifecycle is draft → sent → completed; today everything is a draft. ON DELETE CASCADE means deleting a user takes their documents with them.

4. internal/db/queries/documents.sql (new) — two queries for now: CreateDocument (insert, RETURNING *) and ListDocumentsByOwner (WHERE owner_id = $1 ORDER BY created_at DESC). The owner-scoped read and the draft-guarded delete arrive next lesson. Run sqlc generate and the typed CreateDocument/ListDocumentsByOwner methods appear.

5. internal/config/config.go (modify) — two additions: UploadDir (UPLOAD_DIR, default uploads) and MaxUploadBytes (25 << 20). The comment flags the Railway caveat you will act on in the deploy lesson — the container disk is ephemeral, so prod points UploadDir at a mounted volume.

6. internal/handlers/handlers.go (modify) — the Handlers struct gains a Store storage.Store field, and New takes it. A pure addition alongside the Mailer field from last lesson.

7. cmd/signflow/main.go (modify) — construct the store and hand it to New:

store, err := storage.NewLocalStore(cfg.UploadDir)
if err != nil {
	return err
}
log.Info("file storage: local disk", "dir", cfg.UploadDir)
h := handlers.New(cfg, queries, sessions, mailer, store, log)

NewLocalStore creates the directory if it is missing, so the first run just works.

storage.go CREATE

Create this file in internal/storage/

// Package storage abstracts where uploaded document bytes live.
//
// Dev uses the local filesystem (LocalStore). The interface is the seam for a
// production object store (S3, Cloudflare R2, a Railway Volume) — the same
// pattern as the email.Sender interface. See the README for why this matters on
// Railway, whose container filesystem is ephemeral.
package storage

import (
	"context"
	"io"
)

// Store persists opaque blobs keyed by a string the store itself generates.
type Store interface {
	// Save streams r to storage, returning a freshly generated key, the number
	// of bytes written, and the lowercase hex SHA-256 of the content. The hash
	// is computed in the same pass as the write — the file is never fully
	// buffered in memory.
	Save(ctx context.Context, r io.Reader) (key string, size int64, sha256hex string, err error)
	// Open returns a reader for the blob at key. Caller closes it.
	Open(ctx context.Context, key string) (io.ReadCloser, error)
	// Delete removes the blob. Deleting a missing key is not an error.
	Delete(ctx context.Context, key string) error
}

local.go CREATE

Create this file in internal/storage/

package storage

import (
	"context"
	"crypto/rand"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"io"
	"os"
	"path/filepath"
	"regexp"
)

// LocalStore writes blobs as files under a base directory.
type LocalStore struct {
	dir string
}

// keyPattern matches the keys we generate (32 hex chars). Open/Delete validate
// against it so a stored key can never escape the base dir via path traversal.
var keyPattern = regexp.MustCompile(`^[a-f0-9]{32}$`)

// NewLocalStore ensures dir exists and returns a store rooted there.
func NewLocalStore(dir string) (*LocalStore, error) {
	if err := os.MkdirAll(dir, 0o755); err != nil {
		return nil, fmt.Errorf("create upload dir: %w", err)
	}
	return &LocalStore{dir: dir}, nil
}

func (s *LocalStore) Save(_ context.Context, r io.Reader) (string, int64, string, error) {
	key, err := newKey()
	if err != nil {
		return "", 0, "", err
	}
	path := filepath.Join(s.dir, key)

	f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
	if err != nil {
		return "", 0, "", err
	}

	h := sha256.New()
	size, copyErr := io.Copy(io.MultiWriter(f, h), r) // hash while writing
	closeErr := f.Close()
	if copyErr != nil || closeErr != nil {
		_ = os.Remove(path) // don't leave a half-written file behind
		return "", 0, "", errors.Join(copyErr, closeErr)
	}
	return key, size, hex.EncodeToString(h.Sum(nil)), nil
}

func (s *LocalStore) Open(_ context.Context, key string) (io.ReadCloser, error) {
	path, err := s.safePath(key)
	if err != nil {
		return nil, err
	}
	return os.Open(path)
}

func (s *LocalStore) Delete(_ context.Context, key string) error {
	path, err := s.safePath(key)
	if err != nil {
		return err
	}
	err = os.Remove(path)
	if errors.Is(err, os.ErrNotExist) {
		return nil
	}
	return err
}

func (s *LocalStore) safePath(key string) (string, error) {
	if !keyPattern.MatchString(key) {
		return "", fmt.Errorf("invalid storage key")
	}
	return filepath.Join(s.dir, key), nil
}

func newKey() (string, error) {
	b := make([]byte, 16)
	if _, err := rand.Read(b); err != nil {
		return "", err
	}
	return hex.EncodeToString(b), nil
}

00004_documents.sql CREATE

Create this file in db/migrations/

-- +goose Up
-- +goose StatementBegin
-- A document is any uploaded file, owned by one user. We keep the SHA-256 hash
-- computed at upload time so integrity can be re-checked later (and so a
-- signature can pin the exact bytes that were signed).
--
-- status uses TEXT + CHECK rather than a Postgres ENUM: the set is small and
-- fixed, and TEXT+CHECK is easier to extend later without an ALTER TYPE dance.
-- The lifecycle is draft -> sent -> completed.
CREATE TABLE documents (
    id           UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
    owner_id     UUID        NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    filename     TEXT        NOT NULL,
    content_type TEXT        NOT NULL,
    size         BIGINT      NOT NULL,
    file_hash    TEXT        NOT NULL,               -- SHA-256, hex
    storage_key  TEXT        NOT NULL,               -- opaque key into the file store
    status       TEXT        NOT NULL DEFAULT 'draft'
                 CHECK (status IN ('draft', 'sent', 'completed')),
    created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_documents_owner_id ON documents(owner_id);
-- +goose StatementEnd

-- +goose Down
-- +goose StatementBegin
DROP TABLE documents;
-- +goose StatementEnd

documents.sql CREATE

Create this file in internal/db/queries/

-- name: CreateDocument :one
INSERT INTO documents (owner_id, filename, content_type, size, file_hash, storage_key)
VALUES ($1, $2, $3, $4, $5, $6)
RETURNING *;

-- name: ListDocumentsByOwner :many
SELECT * FROM documents
WHERE owner_id = $1
ORDER BY created_at DESC;

config.go MODIFY 17 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

	// UploadDir is where document files are stored on the local filesystem.
	// NOTE: Railway's container filesystem is ephemeral — see the deploy lesson.
	// In prod, point this at a mounted Railway Volume (or swap in object storage).
	UploadDir string
	// MaxUploadBytes caps a single upload.
	MaxUploadBytes int64
}

// 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"),
		UploadDir:      getenv("UPLOAD_DIR", "uploads"),
		MaxUploadBytes: 25 << 20, // 25 MiB
	}
	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 4 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/storage"
	"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
	Store    storage.Store
	Log      *slog.Logger
}

func New(cfg config.Config, q *db.Queries, sessions *session.Manager, mailer email.Sender, store storage.Store, log *slog.Logger) *Handlers {
	return &Handlers{Cfg: cfg, Queries: q, Sessions: sessions, Mailer: mailer, Store: store, 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 7 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/internal/storage"
	"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)
	store, err := storage.NewLocalStore(cfg.UploadDir)
	if err != nil {
		return err
	}
	log.Info("file storage: local disk", "dir", cfg.UploadDir)
	h := handlers.New(cfg, queries, sessions, mailer, store, 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