file-server/src/FileServer.jl

module FileServer

using Logging
using UUIDs
using HTTP
using JSON3
using Oxygen
using Lux
using JLD2

include("config.jl")
include("job.jl")
include("queue.jl")
include("spool.jl")
include("model.jl")     # build_model() + read_features(); shared with bin/train.jl
include("classify.jl")  # Classifier + load_classifier/classify (needs model.jl)
include("metadata.jl")  # exiftool extraction + sidecar enrichment (stage 2)
include("content.jl")   # binary-vs-text triage for unknown files (stage 3)
include("worker.jl")

# Globals the HTTP handlers read at request time. Set once in `run`, before the
# server starts accepting connections. Declared after the includes above so the
# `Config`/`ChannelQueue` types exist.
const CONFIG = Ref{Config}()
const QUEUE  = Ref{ChannelQueue}()          # stage-1 (classification) queue; HTTP intake enqueues here
const KNOWN_QUEUE = Ref{ChannelQueue}()     # stage-2 (enrichment) queue; stage-1 workers enqueue here
const UNKNOWN_QUEUE = Ref{ChannelQueue}()   # stage-3 (content triage) queue; stage-1 workers enqueue here
const CLASSIFIER = Ref{Classifier}()  # loaded once at startup, shared read-only across workers

include("server.jl")   # registers routes (references CONFIG/QUEUE at call time)

export run

# When stderr is a live terminal Julia flushes each write, but when it's
# redirected to a file or pipe (a log file, `tee`, journald, a container log
# driver) Julia block-buffers it — so a long-running server's logs sit unseen in
# the buffer until it fills or the process exits, making it look like nothing is
# happening. This wrapper delegates to a normal logger and flushes after every
# message so output appears immediately wherever stderr is pointed.
struct FlushLogger{L<:AbstractLogger} <: AbstractLogger
    inner::L
end
Logging.min_enabled_level(f::FlushLogger) = Logging.min_enabled_level(f.inner)
Logging.shouldlog(f::FlushLogger, args...) = Logging.shouldlog(f.inner, args...)
Logging.catch_exceptions(f::FlushLogger) = Logging.catch_exceptions(f.inner)
function Logging.handle_message(f::FlushLogger, args...; kwargs...)
    Logging.handle_message(f.inner, args...; kwargs...)
    flush(f.inner.stream)
    return nothing
end

"""
    run(; overrides...)

Start the file server: build config, ensure directories, recover any leftover
spooled files, spawn the worker pool, then serve HTTP until interrupted
(Ctrl-C / SIGINT or SIGTERM). On shutdown it stops accepting uploads, drains the
queue, waits for workers to finish in-flight files, and exits cleanly.

Keyword `overrides` (e.g. `port=9000`) take precedence over environment vars.
"""
function run(; overrides...)
    # By default a Julia script exits immediately on SIGINT (Ctrl-C). Disable
    # that so the interrupt surfaces as a catchable InterruptException, letting
    # us drain the queue gracefully below.
    Base.exit_on_sigint(false)

    # Flush every log message so output is visible in real time even when stderr
    # is redirected to a file/pipe (see FlushLogger). Set before anything logs.
    global_logger(FlushLogger(ConsoleLogger(stderr)))

    cfg = config_from_env(; overrides...)
    ensure_dirs(cfg)

    # All pools draw from the same OS threads. Warn on the *combined* size (still
    # allowed): oversubscription just means tasks share threads, not a failure.
    total_workers = cfg.worker_count + cfg.known_worker_count + cfg.unknown_worker_count
    if total_workers > Threads.nthreads()
        @warn "combined worker count exceeds available threads; workers will share threads (start Julia with -t N for real parallelism)" classify_workers=cfg.worker_count known_workers=cfg.known_worker_count unknown_workers=cfg.unknown_worker_count total=total_workers nthreads=Threads.nthreads()
    end

    # exiftool is a hard prerequisite for stage-2 enrichment. Fail fast at
    # startup rather than discover it missing on the first known file.
    assert_exiftool()

    queue         = ChannelQueue(cfg.queue_capacity)
    known_queue   = ChannelQueue(cfg.known_queue_capacity)
    unknown_queue = ChannelQueue(cfg.unknown_queue_capacity)
    CONFIG[]        = cfg
    QUEUE[]         = queue
    KNOWN_QUEUE[]   = known_queue
    UNKNOWN_QUEUE[] = unknown_queue

    # Load the classifier before serving. Fail fast: a server that silently
    # doesn't classify is a worse surprise than a clear startup error.
    CLASSIFIER[] = load_classifier(cfg.model_path)
    @info "loaded classifier" path=cfg.model_path

    # Stage-aware recovery: re-drive each stage's leftovers onto its own queue so
    # files resume where they were, not from scratch. spool/ → stage-1,
    # known/ → stage-2, unknown/ → stage-3.
    recovered         = recover_dir!(cfg.spool_dir, queue)
    recovered_known   = recover_dir!(cfg.known_dir, known_queue)
    recovered_unknown = recover_dir!(cfg.unknown_dir, unknown_queue)
    @info "starting file-server" host=cfg.host port=cfg.port workers=cfg.worker_count known_workers=cfg.known_worker_count unknown_workers=cfg.unknown_worker_count capacity=cfg.queue_capacity known_capacity=cfg.known_queue_capacity unknown_capacity=cfg.unknown_queue_capacity recovered=recovered recovered_known=recovered_known recovered_unknown=recovered_unknown

    workers = [Threads.@spawn worker_loop(i, cfg, queue,
                   (job, c, wid) -> handle_classify_job(job, c, wid, known_queue, unknown_queue))
               for i in 1:cfg.worker_count]
    known_workers = [Threads.@spawn worker_loop(i, cfg, known_queue, handle_known_job)
                     for i in 1:cfg.known_worker_count]
    unknown_workers = [Threads.@spawn worker_loop(i, cfg, unknown_queue, handle_unknown_job)
                       for i in 1:cfg.unknown_worker_count]

    register_routes()
    serve(; host = cfg.host, port = cfg.port, async = true, show_banner = false)

    # Idempotent graceful drain: stop accepting uploads, let workers finish the
    # buffered jobs, then exit. Called from two places:
    #   * the `finally` below, for SIGINT (Ctrl-C) and normal return, and
    #   * an `atexit` hook, for SIGTERM (systemd/Docker/k8s `stop`).
    # We can't intercept SIGTERM directly — Julia blocks it on worker threads and
    # handles it in its own runtime, so a user signal() handler never fires. But
    # Julia's SIGTERM path runs `atexit` hooks, which gives us a reliable seam.
    drained = Threads.Atomic{Bool}(false)
    function drain()
        Threads.atomic_xchg!(drained, true) && return   # run at most once
        @info "draining queues and stopping workers"
        terminate()                    # 1. stop accepting new HTTP requests
        close!(queue)                  # 2. no new classify jobs; stage-1 drains buffered
        foreach(wait, workers)         # 3. wait out stage-1 — the ONLY producer of BOTH the
                                       #    known and unknown queues — so nothing else enqueues
        close!(known_queue)            # 4. now safe to close the downstream queues
        close!(unknown_queue)
        foreach(wait, known_workers)   # 5. wait out stage-2 and stage-3
        foreach(wait, unknown_workers)
        @info "shutdown complete"
    end
    atexit(drain)

    try
        while true
            sleep(0.5)            # interruptible; SIGINT throws in here
        end
    catch e
        e isa InterruptException || rethrow(e)
        @info "shutdown requested (SIGINT)"
    finally
        drain()
    end

    return nothing
end

end # module