JsonEnvelopeValidator.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorFsLoader/DirectoryLoader.h>
 
#include <QtCore/QFile>
#include <QtCore/QFileInfo>
#include <QtCore/QJsonDocument>
#include <QtCore/QJsonObject>
#include <QtCore/QLatin1String>
#include <QtCore/QLoggingCategory>
#include <QtCore/QString>
 
#include <optional>
#include <utility>
 
namespace PhosphorFsLoader {
 
struct JsonEnvelope
{
    QString name;
    QJsonObject root;
};
 
inline std::optional<JsonEnvelope> validateJsonEnvelope(const QString& filePath, const QLoggingCategory& category)
{
    // Single source of truth for the JSON-envelope size cap is
    // `DirectoryLoader::kMaxFileBytes`. The loader applies it first via
    // the default sink dispatch path; this helper enforces it again
    // because `validateJsonEnvelope` is a public free function and may
    // be called directly (without a loader stat in front of it). One
    // extra `QFileInfo::size()` per direct call — microscopic compared
    // with the alternative of letting a 2 GiB blob fall through to a
    // caller that didn't stat itself.
    QFileInfo info(filePath);
    if (info.exists() && info.size() > DirectoryLoader::kMaxFileBytes) {
        qCWarning(category).nospace() << "Skipping " << filePath << ": file size " << info.size() << " exceeds limit "
                                      << DirectoryLoader::kMaxFileBytes;
        return std::nullopt;
    }
 
    QFile file(filePath);
    if (!file.open(QIODevice::ReadOnly)) {
        qCWarning(category) << "Skipping unreadable file" << filePath << ":" << file.errorString();
        return std::nullopt;
    }
 
    QJsonParseError parseError;
    const QJsonDocument doc = QJsonDocument::fromJson(file.readAll(), &parseError);
    if (parseError.error != QJsonParseError::NoError) {
        qCWarning(category) << "Skipping malformed JSON" << filePath << ":" << parseError.errorString();
        return std::nullopt;
    }
    if (!doc.isObject()) {
        qCWarning(category) << "Skipping non-object root JSON in" << filePath;
        return std::nullopt;
    }
 
    QJsonObject root = doc.object();
 
    const QString name = root.value(QLatin1String("name")).toString();
    if (name.isEmpty()) {
        qCWarning(category) << "Skipping" << filePath << ": missing required 'name' field";
        return std::nullopt;
    }
 
    // The filename (without extension) is the user's ergonomic handle on
    // the entity; the inner `name` field is what actually gets
    // registered. If the two diverge — typically because the user copied
    // `widget.fade.json → custom.json` and forgot to rename the inner
    // field — the result registers under the inner-name key while the
    // file on disk suggests a different identity. Reject up front with a
    // clear diagnostic naming both sides.
    const QString basename = QFileInfo(filePath).completeBaseName();
    if (name != basename) {
        qCWarning(category).nospace() << "Skipping " << filePath << ": name '" << name << "' does not match filename '"
                                      << basename << "' — rejecting to avoid silent shadowing";
        return std::nullopt;
    }
 
    // Strip the bookkeeping field so the sink's schema-specific
    // `fromJson` doesn't need to know about it (e.g. ProfileLoader's
    // `Profile::fromJson` would otherwise leak `name` into `presetName`).
    root.remove(QLatin1String("name"));
 
    return JsonEnvelope{name, std::move(root)};
}
 
} // namespace PhosphorFsLoader