ZDDC/zddc/internal/handler/converthandler.go

package handler

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log/slog"
	"net/http"
	"os"
	"path/filepath"
	"strings"
	"time"

	"codeberg.org/VARASYS/ZDDC/zddc/internal/config"
	"codeberg.org/VARASYS/ZDDC/zddc/internal/convert"
	"codeberg.org/VARASYS/ZDDC/zddc/internal/zddc"
)

// On-demand MD→{docx,html,pdf} conversion endpoint.
//
//	GET /<path>/foo.docx   (or .html / .pdf)
//
// The URL is the rendered form of a sibling `foo.md` source. The
// dispatcher recognises the pattern via RecognizeVirtualConvert when
// a stat on `foo.docx` (etc.) fails AND `foo.md` exists; only then is
// ServeConverted invoked. A real on-disk `foo.docx` wins precedence
// and serves its bytes normally.
//
// The source file's read policy (enforced by the dispatcher before this
// handler runs) gates the response. The converted bytes are cached at
// <dir>/.zddc.d/converted/<base>.<ext>, with mtime synced to the source — so a
// fast-path GET that finds a fresh cache hit serves the disk file via
// http.ServeContent without invoking pandoc at all.
//
// When the cache is stale (or absent) the handler:
//  1. Reads source bytes.
//  2. Walks the .zddc cascade to assemble the convert.Metadata.
//  3. Calls convert.ToDocx / ToHTML / ToPDF (containerised pandoc).
//  4. Atomically writes the result to .zddc.d/converted/ and syncs mtime.
//  5. Serves it.
//
// Concurrent requests for the same URL share a single conversion via
// the singleflightGroup keyed by the cached-file absolute path.

var convertSF singleflightGroup

// convertTimeout bounds the slow-path conversion + write + serve. The
// runner itself enforces a finer-grained timeout on the container.
const convertTimeout = 90 * time.Second

// convertSourceExts maps a requested target extension to the candidate source
// extensions in precedence order — the first existing real sibling wins. The
// matrix: md↔docx↔html all directions, plus md→pdf (PDF stays markdown-only).
var convertSourceExts = map[string][]string{
	"md":   {"docx", "html"},
	"docx": {"md", "html"},
	"html": {"md", "docx"},
	"pdf":  {"md"},
}

// RecognizeVirtualConvert reports whether urlPath names a virtual
// "<file>.<format>" — a rendered form of a sibling source document in a
// different format. Returns (srcAbsPath, format, true) when the requested
// extension is convertible (md/docx/html/pdf) and a sibling source exists on
// disk, picked by convertSourceExts precedence. The caller (the dispatcher) only
// invokes this when a stat on the requested path itself fails — a real on-disk
// file always wins.
//
// A virtual file URL means `<a href="…/foo.docx">` works without any
// query-string handling, and a script's `curl -O …/foo.md` writes the expected
// filename.
func RecognizeVirtualConvert(fsRoot, urlPath string) (srcAbs, format string, ok bool) {
	lower := strings.ToLower(urlPath)
	for target, sources := range convertSourceExts {
		ext := "." + target
		if !strings.HasSuffix(lower, ext) {
			continue // distinct suffixes — at most one target matches
		}
		base := urlPath[:len(urlPath)-len(ext)]
		if base == "" || strings.HasSuffix(base, "/") {
			return "", "", false
		}
		stem := strings.Trim(base, "/")
		for _, srcExt := range sources {
			abs := filepath.Join(fsRoot, filepath.FromSlash(stem+"."+srcExt))
			// Path containment.
			if abs != fsRoot && !strings.HasPrefix(abs, fsRoot+string(filepath.Separator)) {
				continue
			}
			if info, err := os.Stat(abs); err == nil && !info.IsDir() {
				return abs, target, true
			}
		}
		return "", "", false
	}
	return "", "", false
}

// ServeConverted is the entry point. format is the requested target
// extension; chain is the already-resolved ACL chain (re-used here
// only to extract the convert: cascade metadata).
func ServeConverted(cfg config.Config, w http.ResponseWriter, r *http.Request, srcAbs, format string, chain zddc.PolicyChain) {
	format = strings.ToLower(strings.TrimSpace(format))
	switch format {
	case "md", "docx", "html", "pdf":
	default:
		http.Error(w, "Bad Request — convert must be md, docx, html, or pdf", http.StatusBadRequest)
		return
	}

	caps, ok := convert.Available()
	if !ok {
		// One re-probe attempt — gives the operator a way to recover
		// after building the image without restarting the server.
		caps = convert.Reprobe(r.Context())
		if !caps.Ready() {
			w.Header().Set("Retry-After", "60")
			http.Error(w, "Service Unavailable — "+caps.Reason(), http.StatusServiceUnavailable)
			return
		}
	}

	srcInfo, err := os.Stat(srcAbs)
	if err != nil {
		if errors.Is(err, os.ErrNotExist) {
			http.Error(w, "Not Found", http.StatusNotFound)
		} else {
			http.Error(w, "Internal Server Error", http.StatusInternalServerError)
		}
		return
	}
	if srcInfo.IsDir() {
		http.Error(w, "Bad Request — convert applies to files", http.StatusBadRequest)
		return
	}

	base := strings.TrimSuffix(filepath.Base(srcAbs), filepath.Ext(srcAbs))
	dir := filepath.Dir(srcAbs)
	cacheDir := filepath.Join(dir, ReservedSidecar, "converted")
	cacheAbs := filepath.Join(cacheDir, base+"."+format)

	// Fast path: cached file present and mtime-equal to source.
	if cacheInfo, err := os.Stat(cacheAbs); err == nil && cacheInfo.Mode().IsRegular() {
		if cacheInfo.ModTime().Equal(srcInfo.ModTime()) {
			serveCached(w, r, cacheAbs, format, base)
			return
		}
	}

	// Slow path: convert, cache, serve. Singleflight collapses
	// concurrent requests for the same target.
	_, err = convertSF.Do(cacheAbs, func() (any, error) {
		return nil, buildAndStore(r.Context(), cfg.Root, srcAbs, srcInfo, cacheDir, cacheAbs, format, base, chain)
	})
	if err != nil {
		mapConvertError(w, err, format)
		return
	}

	serveCached(w, r, cacheAbs, format, base)
}

// buildAndStore reads the source, runs the conversion, atomically
// writes the result, and syncs the cached mtime to the source mtime.
// Returns the cached file's absolute path on success.
func buildAndStore(ctx context.Context, fsRoot, srcAbs string, srcInfo os.FileInfo, cacheDir, cacheAbs, format, base string, chain zddc.PolicyChain) error {
	source, err := os.ReadFile(srcAbs)
	if err != nil {
		return fmt.Errorf("read source: %w", err)
	}

	meta := buildMetadata(srcAbs, chain)

	ctx, cancel := context.WithTimeout(ctx, convertTimeout)
	defer cancel()

	// Source format is the on-disk extension; target is the requested format.
	from := strings.TrimPrefix(strings.ToLower(filepath.Ext(srcAbs)), ".")
	var ts convert.TemplateSet
	if format == "html" || format == "pdf" {
		ts = resolveTemplateSet(fsRoot, filepath.Dir(srcAbs), source)
	}
	out, err := convert.Convert(ctx, from, format, source, meta, ts)
	if err != nil {
		return err
	}

	if err := os.MkdirAll(cacheDir, 0o755); err != nil {
		return fmt.Errorf("mkdir cache: %w", err)
	}
	if err := zddc.WriteAtomic(cacheAbs, out); err != nil {
		return fmt.Errorf("write cache: %w", err)
	}
	// Sync mtime to source so the fast-path predicate works on the
	// next request. Both atime and mtime get the source's mtime —
	// http.ServeContent honors mtime for Last-Modified / ETag.
	srcMT := srcInfo.ModTime()
	if err := os.Chtimes(cacheAbs, srcMT, srcMT); err != nil {
		slog.Warn("convert: chtimes failed (continuing)", "path", cacheAbs, "err", err)
	}
	return nil
}

// buildMetadata assembles the Metadata used by pandoc -V flags. The
// filename-derived fields (title, tracking_number, revision, status,
// is_draft) come from zddc.ParseFilename; the project-wide fields
// (client/project/contractor/project_number) come from the cascade.
//
// chain.Levels is walked from leaf (last index, most specific) toward
// root, then Embedded as the final fallback. The first non-empty value
// per field wins.
func buildMetadata(srcAbs string, chain zddc.PolicyChain) convert.Metadata {
	meta := convert.Metadata{
		GenerationTime: time.Now(),
	}

	name := filepath.Base(srcAbs)
	parsed := zddc.ParseFilename(name)
	if parsed.Valid {
		meta.Title = parsed.Title
		meta.TrackingNumber = parsed.TrackingNumber
		meta.Revision = parsed.Revision
		meta.Status = parsed.Status
		meta.IsDraft = strings.Contains(parsed.Revision, "~")
	} else {
		// Strip extension as a last-resort title.
		stem := strings.TrimSuffix(name, filepath.Ext(name))
		meta.Title = stem
	}

	apply := func(zf zddc.ZddcFile) {
		if zf.Convert == nil {
			return
		}
		if meta.Client == "" {
			meta.Client = zf.Convert.Client
		}
		if meta.Project == "" {
			meta.Project = zf.Convert.Project
		}
		if meta.Contractor == "" {
			meta.Contractor = zf.Convert.Contractor
		}
		if meta.ProjectNumber == "" {
			meta.ProjectNumber = zf.Convert.ProjectNumber
		}
	}
	// Leaf → root.
	for i := len(chain.Levels) - 1; i >= 0; i-- {
		apply(chain.Levels[i])
	}
	apply(chain.Embedded)

	return meta
}

// serveCached writes the cached file with the correct headers. ETag is
// derived from the source's mtime so a refresh changes it cleanly.
func serveCached(w http.ResponseWriter, r *http.Request, cacheAbs, format, base string) {
	f, err := os.Open(cacheAbs)
	if err != nil {
		http.Error(w, "Internal Server Error", http.StatusInternalServerError)
		return
	}
	defer f.Close()
	info, err := f.Stat()
	if err != nil {
		http.Error(w, "Internal Server Error", http.StatusInternalServerError)
		return
	}

	w.Header().Set("Content-Type", contentTypeFor(format))
	w.Header().Set("Content-Disposition", contentDispositionFor(format, base))
	w.Header().Set("X-ZDDC-Source", "convert:"+format)
	// http.ServeContent handles If-Modified-Since / Range / etc. and
	// emits Last-Modified from info.ModTime(). The clients we ship
	// don't issue conditional GETs for conversions today, but other
	// callers might.
	http.ServeContent(w, r, filepath.Base(cacheAbs), info.ModTime(), f)
}

func contentTypeFor(format string) string {
	switch format {
	case "docx":
		return "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
	case "html":
		return "text/html; charset=utf-8"
	case "pdf":
		return "application/pdf"
	}
	return "application/octet-stream"
}

// contentDispositionFor returns the disposition header. HTML is served
// inline (so the browser renders the rich viewer template directly);
// DOCX and PDF are inline too but the browse client adds the anchor's
// `download` attribute, which forces save-as. Filename is the source
// stem + the target extension so the user gets `foo.docx`, not
// `foo.md.docx`.
func contentDispositionFor(format, base string) string {
	return fmt.Sprintf(`inline; filename="%s.%s"`, base, format)
}

// purgeConverted removes the cached .zddc.d/converted/<base>.{md,docx,html,pdf}
// sidecars for a convertible source. Called from the file API after a successful
// PUT/DELETE/MOVE so the next virtual-convert GET regenerates. Best-effort:
// errors (including "directory doesn't exist") are swallowed. Sources whose
// extension isn't convertible are a no-op, so this is safe to call
// unconditionally after any write.
func purgeConverted(srcAbs string) {
	ext := strings.TrimPrefix(strings.ToLower(filepath.Ext(srcAbs)), ".")
	if _, ok := convertSourceExts[ext]; !ok {
		return
	}
	dir := filepath.Dir(srcAbs)
	base := strings.TrimSuffix(filepath.Base(srcAbs), filepath.Ext(srcAbs))
	for target := range convertSourceExts {
		_ = os.Remove(filepath.Join(dir, ReservedSidecar, "converted", base+"."+target))
	}
}

func mapConvertError(w http.ResponseWriter, err error, format string) {
	if errors.Is(err, convert.ErrUnavailable) {
		w.Header().Set("Retry-After", "60")
		http.Error(w, "Service Unavailable — conversion runtime not available", http.StatusServiceUnavailable)
		return
	}
	var ce *convert.ConvertError
	if errors.As(err, &ce) {
		// Timeout → 504. Non-zero exit with stderr → 422 with the
		// stderr excerpt so the client can show a real message.
		if ce.Cause != nil && errors.Is(ce.Cause, context.DeadlineExceeded) {
			http.Error(w, "Gateway Timeout — conversion timed out", http.StatusGatewayTimeout)
			return
		}
		msg := strings.TrimSpace(ce.Stderr)
		if msg == "" {
			msg = ce.Error()
		}
		if len(msg) > 1024 {
			msg = msg[:1024]
		}
		http.Error(w, "Unprocessable Entity — "+msg, http.StatusUnprocessableEntity)
		return
	}
	slog.Warn("convert: unexpected error", "format", format, "err", err)
	http.Error(w, "Internal Server Error", http.StatusInternalServerError)
}

// FrontMatterTemplatePath is the JSON endpoint that exposes the recognised
// markdown front-matter fields + a ready-made greyed placeholder string. The
// browse markdown editor fetches it (server mode) to communicate the valid
// keys to authors without baking the list into client JS — it stays in sync
// with convert.RecognizedFrontMatter, the server-side source of truth.
const FrontMatterTemplatePath = "/.api/frontmatter"

// ServeFrontMatterTemplate returns the recognised front-matter fields and the
// editor placeholder as JSON. Read-only, no auth gate: it leaks nothing beyond
// the documented field names. GET/HEAD only.
func ServeFrontMatterTemplate(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodGet && r.Method != http.MethodHead {
		w.Header().Set("Allow", "GET, HEAD")
		http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed)
		return
	}
	payload := struct {
		Placeholder string                     `json:"placeholder"`
		Fields      []convert.FrontMatterField `json:"fields"`
	}{
		Placeholder: convert.FrontMatterPlaceholder(),
		Fields:      convert.RecognizedFrontMatter(),
	}
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.Header().Set("Cache-Control", "max-age=300")
	if r.Method == http.MethodHead {
		return
	}
	_ = json.NewEncoder(w).Encode(payload)
}