feat(api): enhance image module management and export functionality
- Added read-write access to the darktable SQLite catalog for module parameter edits. - Implemented new endpoints for exporting images and retrieving full-resolution images. - Introduced PATCH method for updating module parameters with optional preview. - Added comprehensive tests for new API functionalities, including module retrieval and error handling. - Updated CORS headers to support new HTTP methods. - Created detailed documentation for new API endpoints and module operations.
This commit is contained in:
@@ -5,6 +5,8 @@ local auth = require "auth"
|
||||
local db = require "db"
|
||||
local preview = require "preview"
|
||||
local config = require "config"
|
||||
local modules = require "modules"
|
||||
local socket = require "socket"
|
||||
|
||||
-- ── Refresh queue (IPC with the darktable bridge plugin) ──────────────────────
|
||||
-- The bridge plugin running inside darktable polls this file and calls
|
||||
@@ -26,6 +28,21 @@ local function enqueue_refresh(image_id)
|
||||
return true
|
||||
end
|
||||
|
||||
local function enqueue_export(image_id)
|
||||
local qf = config.export_queue
|
||||
local f, ferr = io.open(qf, "a")
|
||||
if not f then
|
||||
return false, "cannot open export queue " .. qf .. ": " .. (ferr or "?")
|
||||
end
|
||||
f:write(tostring(image_id) .. "\n")
|
||||
f:close()
|
||||
return true
|
||||
end
|
||||
|
||||
local function export_path(image_id)
|
||||
return config.export_dir .. "/" .. tostring(image_id) .. ".jpg"
|
||||
end
|
||||
|
||||
local M = {}
|
||||
|
||||
-- ── Helpers ───────────────────────────────────────────────────────────────────
|
||||
@@ -218,11 +235,10 @@ end
|
||||
|
||||
-- ── Cache refresh ─────────────────────────────────────────────────────────────
|
||||
-- POST /api/v1/images/:id/refresh
|
||||
-- Enqueues an image ID for cache regeneration by the darktable bridge plugin.
|
||||
-- The bridge plugin (darktable-api-bridge.lua) running inside a live darktable
|
||||
-- instance calls image:drop_cache() + image:generate_cache() when it drains
|
||||
-- the queue. Returns 202 Accepted immediately; the actual regeneration happens
|
||||
-- asynchronously inside darktable.
|
||||
-- Enqueues the image for thumbnail regeneration via the darktable bridge.
|
||||
-- The bridge calls image:drop_cache() + image:generate_cache(true, …), which
|
||||
-- re-renders through darktable's full processing pipeline so that development
|
||||
-- settings (tone curves, exposure, colour grading, etc.) are reflected.
|
||||
-- Requires scope: cache:refresh
|
||||
function M.refresh_cache(req)
|
||||
local payload, s, b, ct = require_auth(req, "cache:refresh")
|
||||
@@ -231,7 +247,6 @@ function M.refresh_cache(req)
|
||||
local id = tonumber(req.path_params.id)
|
||||
if not id then return err(400, "invalid_id", "id must be an integer") end
|
||||
|
||||
-- Verify the image exists in the catalog before queuing
|
||||
local img = db.get_image(id)
|
||||
if not img then return err(404, "not_found", "image " .. id .. " not found") end
|
||||
|
||||
@@ -245,8 +260,219 @@ function M.refresh_cache(req)
|
||||
image_id = id,
|
||||
filename = img.filename,
|
||||
queue = config.refresh_queue,
|
||||
message = "cache refresh enqueued; darktable bridge will process it shortly",
|
||||
message = "cache refresh enqueued; darktable bridge will re-render thumbnails shortly",
|
||||
}), "application/json; charset=utf-8"
|
||||
end
|
||||
|
||||
-- ── Development modules ───────────────────────────────────────────────────────
|
||||
-- GET /api/v1/images/:id/modules
|
||||
-- Returns every operation in the history stack (active entry per operation).
|
||||
-- Response includes decoded params for known modules; base64 blob for others.
|
||||
-- Requires scope: images:read
|
||||
function M.list_modules(req)
|
||||
local payload, s, b, ct = require_auth(req, "images:read")
|
||||
if not payload then return s, b, ct end
|
||||
|
||||
local id = tonumber(req.path_params.id)
|
||||
if not id then return err(400, "invalid_id", "id must be an integer") end
|
||||
|
||||
local img = db.get_image(id)
|
||||
if not img then return err(404, "not_found", "image " .. id .. " not found") end
|
||||
|
||||
local mods = db.list_modules(id)
|
||||
return ok({ image_id = id, items = mods })
|
||||
end
|
||||
|
||||
-- GET /api/v1/images/:id/modules/:op
|
||||
-- Returns the active history entry for one operation.
|
||||
-- Requires scope: images:read
|
||||
function M.get_module(req)
|
||||
local payload, s, b, ct = require_auth(req, "images:read")
|
||||
if not payload then return s, b, ct end
|
||||
|
||||
local id = tonumber(req.path_params.id)
|
||||
local op = req.path_params.op
|
||||
if not id then return err(400, "invalid_id", "id must be an integer") end
|
||||
|
||||
local img = db.get_image(id)
|
||||
if not img then return err(404, "not_found", "image " .. id .. " not found") end
|
||||
|
||||
local mod = db.get_module(id, op)
|
||||
if not mod then
|
||||
return err(404, "module_not_found",
|
||||
"operation '" .. op .. "' not in history for image " .. id)
|
||||
end
|
||||
return ok(mod)
|
||||
end
|
||||
|
||||
-- PATCH /api/v1/images/:id/modules/:op
|
||||
-- Body (JSON):
|
||||
-- {
|
||||
-- "enabled": true|false, -- optional: change enabled state
|
||||
-- "params": { field: value, … } -- optional: named params for known modules
|
||||
-- "params_b64": "<base64>" -- alternative: raw binary for unknown modules
|
||||
-- }
|
||||
-- Query param: ?preview=thumb|small|medium|large|xlarge
|
||||
-- If given, waits up to 30 s for the thumbnail to update and returns the JPEG.
|
||||
-- Otherwise returns 204 No Content.
|
||||
-- Requires scope: cache:refresh
|
||||
function M.patch_module(req)
|
||||
local payload, s, b, ct = require_auth(req, "cache:refresh")
|
||||
if not payload then return s, b, ct end
|
||||
|
||||
local id = tonumber(req.path_params.id)
|
||||
local op = req.path_params.op
|
||||
if not id then return err(400, "invalid_id", "id must be an integer") end
|
||||
|
||||
local img = db.get_image(id)
|
||||
if not img then return err(404, "not_found", "image " .. id .. " not found") end
|
||||
|
||||
local mod = db.get_module(id, op)
|
||||
if not mod then
|
||||
return err(404, "module_not_found",
|
||||
"operation '" .. op .. "' not in history for image " .. id)
|
||||
end
|
||||
|
||||
-- Parse request body
|
||||
local body = parse_body(req)
|
||||
if not body then
|
||||
return err(400, "invalid_body", "could not parse JSON body")
|
||||
end
|
||||
|
||||
local new_enabled = body.enabled -- may be nil (leave unchanged)
|
||||
local new_blob = nil
|
||||
|
||||
if body.params_b64 then
|
||||
-- Caller provided raw base64 params (for unknown modules)
|
||||
local ok_dec, decoded = pcall(require("base64").decode, body.params_b64)
|
||||
if not ok_dec then
|
||||
return err(400, "invalid_params_b64", "base64 decode failed")
|
||||
end
|
||||
new_blob = decoded
|
||||
elseif body.params then
|
||||
if mod.params then
|
||||
local existing_blob = db.get_module_blob(id, op)
|
||||
if not existing_blob then
|
||||
return err(500, "db_error", "could not read existing params blob")
|
||||
end
|
||||
new_blob = modules.encode(op, mod.module_version, existing_blob, body.params)
|
||||
if not new_blob then
|
||||
return err(400, "unsupported_module",
|
||||
"named-param editing is not supported for operation '" .. op ..
|
||||
"'; use params_b64 with a raw binary blob instead")
|
||||
end
|
||||
else
|
||||
-- Unknown module, caller must supply params_b64
|
||||
return err(400, "params_required",
|
||||
"operation '" .. op .. "' requires params_b64 (binary blob) for editing")
|
||||
end
|
||||
end
|
||||
|
||||
-- Persist to history table
|
||||
local ok_write, werr = db.set_module_params(id, op, new_enabled, new_blob)
|
||||
if not ok_write then
|
||||
return err(500, "db_write_error", werr)
|
||||
end
|
||||
|
||||
-- Enqueue a thumbnail refresh so the bridge re-renders with the new params.
|
||||
enqueue_refresh(id)
|
||||
|
||||
-- Optional synchronous preview response
|
||||
local preview_size = req.params.preview
|
||||
if preview_size and preview_size ~= "" then
|
||||
-- Read the thumbnail before the refresh so we can detect when it changes.
|
||||
local old_data = preview.get(id, img.path, img.filename, preview_size)
|
||||
local deadline = os.time() + 30
|
||||
local new_data
|
||||
while os.time() < deadline do
|
||||
socket.select(nil, nil, 0.5)
|
||||
local candidate = preview.get(id, img.path, img.filename, preview_size)
|
||||
if candidate and candidate ~= old_data then
|
||||
new_data = candidate
|
||||
break
|
||||
end
|
||||
end
|
||||
if new_data then
|
||||
return 200, new_data, "image/jpeg"
|
||||
end
|
||||
-- Timeout — return what we have (may be stale) with a warning header
|
||||
local fallback = preview.get(id, img.path, img.filename, preview_size)
|
||||
if fallback then
|
||||
return 200, fallback, "image/jpeg",
|
||||
{ ["X-Preview-Warning"] = "regeneration-timeout; thumbnail may be stale" }
|
||||
end
|
||||
return err(504, "preview_timeout",
|
||||
"thumbnail regeneration timed out after 30 s; retry the preview endpoint")
|
||||
end
|
||||
|
||||
return 204, "", nil
|
||||
end
|
||||
|
||||
-- ── Full-resolution export ────────────────────────────────────────────────────
|
||||
-- POST /api/v1/images/:id/export
|
||||
-- Enqueues a full-resolution JPEG export via the darktable bridge.
|
||||
-- The bridge calls dt.new_format("jpeg"):write_image() which runs the complete
|
||||
-- development pipeline. Returns 202 immediately; poll GET /full to check when ready.
|
||||
-- Requires scope: cache:refresh
|
||||
function M.trigger_export(req)
|
||||
local payload, s, b, ct = require_auth(req, "cache:refresh")
|
||||
if not payload then return s, b, ct end
|
||||
|
||||
local id = tonumber(req.path_params.id)
|
||||
if not id then return err(400, "invalid_id", "id must be an integer") end
|
||||
|
||||
local img = db.get_image(id)
|
||||
if not img then return err(404, "not_found", "image " .. id .. " not found") end
|
||||
|
||||
local queued, qerr = enqueue_export(id)
|
||||
if not queued then
|
||||
return err(500, "queue_error", qerr)
|
||||
end
|
||||
|
||||
return 202, json.encode({
|
||||
status = "accepted",
|
||||
image_id = id,
|
||||
filename = img.filename,
|
||||
export = export_path(id),
|
||||
message = "full-resolution export enqueued; poll GET /api/v1/images/" .. id .. "/full when ready",
|
||||
}), "application/json; charset=utf-8"
|
||||
end
|
||||
|
||||
-- GET /api/v1/images/:id/full
|
||||
-- Serves the full-resolution JPEG previously exported via POST /export.
|
||||
-- If no export exists yet, enqueues one and returns 202 so the client can retry.
|
||||
-- Requires scope: previews:read
|
||||
function M.get_full(req)
|
||||
local payload, s, b, ct = require_auth(req, "previews:read")
|
||||
if not payload then return s, b, ct end
|
||||
|
||||
local id = tonumber(req.path_params.id)
|
||||
if not id then return err(400, "invalid_id", "id must be an integer") end
|
||||
|
||||
local img = db.get_image(id)
|
||||
if not img then return err(404, "not_found", "image " .. id .. " not found") end
|
||||
|
||||
local path = export_path(id)
|
||||
local f = io.open(path, "rb")
|
||||
if f then
|
||||
local data = f:read("*a")
|
||||
f:close()
|
||||
return 200, data, "image/jpeg"
|
||||
end
|
||||
|
||||
-- Not yet exported — enqueue and tell the client to retry.
|
||||
local queued, qerr = enqueue_export(id)
|
||||
if not queued then
|
||||
return err(500, "queue_error", qerr)
|
||||
end
|
||||
|
||||
return 202, json.encode({
|
||||
status = "queued",
|
||||
image_id = id,
|
||||
filename = img.filename,
|
||||
retry_after = 5,
|
||||
message = "export enqueued; retry in a few seconds",
|
||||
}), "application/json; charset=utf-8", { ["Retry-After"] = "5" }
|
||||
end
|
||||
|
||||
return M
|
||||
|
||||
Reference in New Issue
Block a user