feat: production-ready hardening, TLS SMTP, pluggable content, docs

[christiangda]

Summary

Makes mailer production-ready: fixes a concurrency deadlock, adds TLS to the SMTP transport, makes MailContent usable by external backends, hardens validation, and adds documentation, tests, and public-library tooling.

Highlights

Correctness & concurrency

• Fixed a deadlock. Enqueue previously held an exclusive mutex during a blocking channel send, so a full queue could block Start/Stop indefinitely (reproducible via the old TestMailService_EnqueueBlocksWhenFull, which hung for 60s). The service now uses an RWMutex + atomic started flag; the queue is closed exactly once under the write lock while Enqueue holds the read lock — no send-on-closed-channel, no deadlock.
• Start/Stop are now idempotent and safe for concurrent use.

Pluggable backends actually work

• MailContent now exposes read accessors (FromName, FromAddress, ToName, ToAddress, MimeType, Subject, Body). Previously all fields were unexported with no getters, so any external MailerService implementation could not read the message it was asked to send.

SMTP transport (security)

• TLS support: implicit TLS/SMTPS (ImplicitTLS, implied on port 465) and opportunistic/required STARTTLS (RequireTLS). Without this, PLAIN auth against a real server fails (stdlib refuses plaintext auth) — the transport was effectively unusable for authenticated servers.
• Configurable DialTimeout, LocalName (EHLO), custom TLSConfig; full 1–65535 port range; CRLF line endings + UTF-8 Content-Type; errors wrap their cause (errors.Is/errors.As).

Validation & injection safety

• Rejects CR/LF/NUL in header fields (SMTP header/command injection).
• Address limits raised to RFC-compatible bounds (254); body limit raised to 256 KiB.

Service ergonomics

• MailServiceConfig.QueueSize (queue independent of worker count) and per-message Timeout.

Tests, docs, tooling

• In-process SMTP test server exercising plain, STARTTLS, and implicit-TLS paths; concurrency tests under -race; validation/getter coverage. ~92% statement coverage (gate in .testcoverage.yml passes).
• Rewritten README (install, quick start, config tables, custom backends), removed the retired Go Report Card badge, new docs/ guides + examples.
• Added Makefile, .golangci.yaml (lint clean), DEVELOPMENT_GUIDELINES.md, CHANGELOG.md; expanded SECURITY.md.

Compatibility

Pre-1.0. Additive API (accessors, new config fields). Behavioral changes: SMTP now negotiates TLS, SMTPPort allowlist replaced by a range check, and validation bounds widened — all documented in CHANGELOG.md.

Verification

gofmt -l .          # clean
go vet ./...        # clean
go test -race ./... # pass
golangci-lint run   # 0 issues
go-test-coverage    # PASS (92.1%)

🤖 Generated with Claude Code