Files
DarkflameServer/dDashboardServer/routes/OpenApi.h
Aaron Kimbrell a4c4c24a5c feat(dashboard): the zone file API, with zone edit locks
/api/v1/zones/{zoneId}: send a zone's edited files (multipart), follow the reload,
list, restore and clear the zone's sets, and take, release and look at its lock.
Every request needs an API key that names the zones_publish permission, an owner at
zone_publish_gm_level, and HTTPS or the server's own machine; refusals are counted
per address and every use is in the audit log. A publish is checked at its headers
before any of its body is taken, the files are checked and written on a worker
thread, and the zone's instances are replaced through the world reload, held while
players are there unless told to move them.

The Worlds page lists each zone's editors and lock holder for an admin.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-10 19:34:43 -06:00

236 lines
11 KiB
C++

#pragma once
#include <cctype>
#include <string>
#include <string_view>
#include <vector>
#include "json.hpp"
/**
* The dashboard's API as an OpenAPI 3 document, for Swagger UI on the API page (where each call can be tried out).
*
* Built from the registered routes: `:id` path parts become path parameters, and the parameters written in a route's
* description in the house style become query parameters and a request body:
* "Query: ?range=24h|7d|30d, &files= (newest per server)" or "Query: after (the last id), limit (max 500)"
* "Body: {name, enabled, parent (default root.xml)}" (also "Body (optional): {...}", "Body adds {...}")
* Routes described as "(DataTables)" take the DataTables paging body; ones described as "(multipart)" take
* multipart/form-data: the fields of their "Body: {...}" and file parts. Pure (routes in, JSON out) so it can be tested.
*/
namespace OpenApi {
struct Route {
std::string method; // GET, POST, ...
std::string path; // /api/accounts/:id
std::string description;
int minGmLevel{};
std::string permission; // empty when the route needs a GM level rather than a named permission
};
struct Param {
std::string name;
std::string description;
std::vector<std::string> choices; // from "a|b|c"
bool isList{}; // "name: [...]"
};
namespace Detail {
inline std::string Trim(std::string_view text) {
size_t start = 0, end = text.size();
while (start < end && std::isspace(static_cast<unsigned char>(text[start]))) start++;
while (end > start && std::isspace(static_cast<unsigned char>(text[end - 1]))) end--;
return std::string(text.substr(start, end - start));
}
// Split on commas and '&' that aren't inside (), [] or {}
inline std::vector<std::string> SplitTopLevel(std::string_view text) {
std::vector<std::string> parts;
int depth = 0;
size_t start = 0;
for (size_t i = 0; i < text.size(); i++) {
const char c = text[i];
if (c == '(' || c == '[' || c == '{') depth++;
else if ((c == ')' || c == ']' || c == '}') && depth > 0) depth--;
else if ((c == ',' || c == '&') && depth == 0) {
parts.push_back(Trim(text.substr(start, i - start)));
start = i + 1;
}
}
parts.push_back(Trim(text.substr(start)));
return parts;
}
// "?range=24h|7d|30d", "&files= (newest per server)", "after (the last id)", "changes: [{...}]"
inline std::optional<Param> ParseParam(std::string text) {
while (!text.empty() && (text[0] == '?' || text[0] == '&')) text.erase(0, 1);
size_t i = 0;
while (i < text.size() && (std::isalnum(static_cast<unsigned char>(text[i])) || text[i] == '_')) i++;
if (i == 0) return std::nullopt;
Param param{ text.substr(0, i) };
auto rest = Trim(std::string_view(text).substr(i));
if (rest.starts_with("=")) {
auto value = rest.substr(1);
const auto space = value.find_first_of(" (");
const auto choices = Trim(std::string_view(value).substr(0, space));
rest = space == std::string::npos ? "" : Trim(std::string_view(value).substr(space));
if (choices.find('|') != std::string::npos) {
size_t from = 0;
for (size_t bar = choices.find('|'); ; bar = choices.find('|', from)) {
param.choices.push_back(choices.substr(from, bar == std::string::npos ? std::string::npos : bar - from));
if (bar == std::string::npos) break;
from = bar + 1;
}
}
} else if (rest.starts_with(":")) {
param.isList = Trim(std::string_view(rest).substr(1)).starts_with("[");
rest = "";
}
if (rest.starts_with("(") && rest.ends_with(")")) rest = rest.substr(1, rest.size() - 2);
param.description = rest;
return param;
}
// The text after `marker` up to the end of its sentence (a ". " outside brackets, or the end)
inline std::optional<std::string> Clause(const std::string& text, const std::string& marker) {
const auto at = text.find(marker);
if (at == std::string::npos) return std::nullopt;
const auto start = at + marker.size();
int depth = 0;
for (size_t i = start; i < text.size(); i++) {
const char c = text[i];
if (c == '(' || c == '[' || c == '{') depth++;
else if ((c == ')' || c == ']' || c == '}') && depth > 0) depth--;
else if (depth == 0 && c == '.' && (i + 1 == text.size() || text[i + 1] == ' ')) return Trim(std::string_view(text).substr(start, i - start));
}
return Trim(std::string_view(text).substr(start));
}
// The first {...} (balanced) at or after `from`
inline std::optional<std::string> Braces(const std::string& text, size_t from) {
const auto open = text.find('{', from);
if (open == std::string::npos) return std::nullopt;
int depth = 0;
for (size_t i = open; i < text.size(); i++) {
if (text[i] == '{') depth++;
else if (text[i] == '}' && --depth == 0) return text.substr(open + 1, i - open - 1);
}
return std::nullopt;
}
}
inline std::vector<Param> QueryParams(const std::string& description) {
std::vector<Param> params;
const auto clause = Detail::Clause(description, "Query:");
if (!clause) return params;
for (const auto& part : Detail::SplitTopLevel(*clause)) {
if (auto param = Detail::ParseParam(part)) params.push_back(std::move(*param));
}
return params;
}
inline std::vector<Param> BodyParams(const std::string& description) {
std::vector<Param> params;
const auto at = description.find("Body");
if (at == std::string::npos) return params;
const auto braces = Detail::Braces(description, at);
if (!braces) return params;
for (const auto& part : Detail::SplitTopLevel(*braces)) {
if (auto param = Detail::ParseParam(part)) params.push_back(std::move(*param));
}
return params;
}
// The first sentence, for the one-line summary
inline std::string Summary(const std::string& description) {
const auto clause = Detail::Clause(" " + description, " ");
auto summary = clause ? *clause : description;
return summary.size() > 120 ? summary.substr(0, 117) + "..." : summary;
}
inline nlohmann::json Build(const std::vector<Route>& routes, const std::string& title) {
nlohmann::json paths = nlohmann::json::object();
for (const auto& route : routes) {
std::string path;
nlohmann::json parameters = nlohmann::json::array();
std::string tag;
size_t segment = 0;
for (size_t i = 0; i < route.path.size();) {
const auto next = route.path.find('/', i + 1);
auto part = route.path.substr(i + 1, (next == std::string::npos ? route.path.size() : next) - i - 1);
if (part.starts_with(":")) {
part = part.substr(1);
parameters.push_back({ {"name", part}, {"in", "path"}, {"required", true}, {"schema", { {"type", "string"} }} });
path += "/{" + part + "}";
} else {
path += "/" + part;
if (segment == 1) tag = part; // /api/<tag>/...
}
segment++;
if (next == std::string::npos) break;
i = next;
}
for (const auto& param : QueryParams(route.description)) {
nlohmann::json schema{ {"type", "string"} };
if (!param.choices.empty()) schema["enum"] = param.choices;
parameters.push_back({ {"name", param.name}, {"in", "query"}, {"required", false}, {"description", param.description}, {"schema", schema} });
}
auto method = route.method;
for (auto& c : method) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
std::string access = route.permission.empty()
? (route.minGmLevel <= 0 ? "Any signed-in account" : "GM " + std::to_string(route.minGmLevel) + "+")
: "Permission `" + route.permission + "` (GM " + std::to_string(route.minGmLevel) + "+ now)";
nlohmann::json operation{
{"summary", Summary(route.description)},
{"description", route.description + "\n\n**Who:** " + access},
{"tags", { tag.empty() ? "pages" : tag }},
{"parameters", parameters},
{"responses", { {"200", { {"description", "OK"} }}, {"400", { {"description", "Bad request: {error}"} }},
{"401", { {"description", "Not signed in"} }}, {"403", { {"description", "Not allowed at your GM level"} }}, {"404", { {"description", "Not found"} }} }}
};
if (!route.permission.empty()) operation["x-permission"] = route.permission;
if (method != "get") {
nlohmann::json properties = nlohmann::json::object(), example = nlohmann::json::object();
if (route.description.find("(DataTables)") != std::string::npos) {
for (const auto& [name, value] : { std::pair<const char*, nlohmann::json>{ "draw", 1 }, { "start", 0 }, { "length", 25 }, { "search", "" } }) {
properties[name] = { {"type", value.is_string() ? "string" : "integer"} };
example[name] = value;
}
}
for (const auto& param : BodyParams(route.description)) {
nlohmann::json schema = param.isList ? nlohmann::json{ {"type", "array"}, {"items", nlohmann::json::object()} } : nlohmann::json::object();
if (!param.choices.empty()) schema["enum"] = param.choices;
if (!param.description.empty()) schema["description"] = param.description;
properties[param.name] = schema;
example[param.name] = param.isList ? nlohmann::json::array() : nlohmann::json(param.choices.empty() ? "" : param.choices.front());
}
if (route.description.find("(multipart)") != std::string::npos) {
// File uploads: the fields from "Body: {...}", and any number of file parts
properties["files"] = { {"type", "array"}, {"items", { {"type", "string"}, {"format", "binary"} }},
{"description", "One part per file; each part's filename is the file's path"} };
operation["requestBody"] = { {"required", true}, {"content", { {"multipart/form-data", { {"schema", { {"type", "object"}, {"properties", properties} }} }} }} };
operation["responses"]["409"] = { {"description", "Conflict: {error, message}"} };
operation["responses"]["413"] = { {"description", "Too large"} };
operation["responses"]["422"] = { {"description", "Refused: {error: validation_failed, files: [{path, ok, errors: [{code, message, offset}]}]}"} };
operation["responses"]["429"] = { {"description", "Too many requests"} };
} else {
operation["requestBody"] = { {"required", false}, {"content", { {"application/json", { {"schema", { {"type", "object"}, {"properties", properties} }}, {"example", example} }} }} };
}
}
paths[path][method] = operation;
}
return {
{"openapi", "3.0.3"},
{"info", { {"title", title}, {"version", "1"},
{"description", "Every endpoint your account may use. Sign in on the dashboard (your session is used here) or send "
"`Authorization: Bearer <token>` with a token from your account page. Requests signed in with the session cookie must also "
"send `X-Requested-With` (this page does)."} }},
{"components", { {"securitySchemes", {
{"bearer", { {"type", "http"}, {"scheme", "bearer"}, {"description", "An API key from your account page"} }},
{"session", { {"type", "apiKey"}, {"in", "cookie"}, {"name", "dashboardToken"}, {"description", "Your dashboard sign-in"} }} }} }},
{"security", { { {"session", nlohmann::json::array()} }, { {"bearer", nlohmann::json::array()} } }},
{"paths", paths}
};
}
}