Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IpcProtocol.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3#pragma once
4
5#include <PhosphorIpc/phosphoripc_export.h>
6
7#include <QByteArray>
8#include <QJsonObject>
9#include <QJsonValue>
10#include <QString>
11#include <QVariant>
12#include <QVariantList>
13
14#include <optional>
15
16// Wire-format definitions for the JSON-over-Unix-socket protocol the
17// IpcRouter speaks. Shared between libs/phosphor-ipc
18// (server) and phosphor-shell/cli/phosphorctl (client); both link this
19// library so the constants and parsers stay in lockstep. Mirrors the
20// split of libs/phosphor-protocol (PhosphorProtocol/
21// WindowTypes.h and WindowMarshalling.h); JSON is self-describing so we
22// ship the type constants only, no Qt-marshalling boilerplate.
23//
24// Wire shape: one JSON object per line, '\n'-terminated, UTF-8.
25// (Same NDJSON shape as niri-ipc, hyprland-ipc.)
26//
27// CMake mirrors the protocol-version constant via the
28// PHOSPHOR_IPC_PROTOCOL_VERSION compile definition so this header
29// and the build agree at compile time. Bumped whenever the
30// JSON shape on the wire changes incompatibly.
31
32namespace PhosphorIpc {
33
34constexpr int ProtocolVersion = 1;
35
36#ifdef PHOSPHOR_IPC_PROTOCOL_VERSION
37static_assert(PHOSPHOR_IPC_PROTOCOL_VERSION == ProtocolVersion,
38 "CMake's PHOSPHOR_IPC_PROTOCOL_VERSION must match IpcProtocol.h's ProtocolVersion");
39#endif
40
41// Field names used across the wire. Declared as constexpr string
42// literals so usage sites can pass them to QJsonObject without
43// constructing QString, and the compiler catches typos at the
44// definition site instead of letting them silently land in the
45// wire format.
46namespace Field {
47constexpr auto Type = "type";
48constexpr auto Id = "id";
49constexpr auto Target = "target";
50constexpr auto Fn = "fn";
51constexpr auto Args = "args";
52constexpr auto Signal = "signal";
53constexpr auto SubscriptionId = "subscriptionId";
54constexpr auto Result = "result";
55constexpr auto Code = "code";
56constexpr auto Message = "message";
57constexpr auto Detail = "detail";
58} // namespace Field
59
60// Request `type` discriminator values. Sent by the client.
61namespace RequestType {
62constexpr auto Call = "call";
63constexpr auto List = "list";
64constexpr auto Schema = "schema";
65constexpr auto Subscribe = "subscribe";
66constexpr auto Unsubscribe = "unsubscribe";
67} // namespace RequestType
68
69// Response `type` discriminator values. Sent by the server.
70namespace ResponseType {
71constexpr auto Reply = "reply"; // call / list / schema result, subscribe / unsubscribe ack
72// Pushed signal payload: to a subscriber (carries `subscriptionId`), or
73// to one connection through IpcRouter::sendEvent (carries `target` and
74// `signal` in place of a subscriptionId).
75constexpr auto Event = "event";
76constexpr auto Error = "error"; // request-correlated failure
77} // namespace ResponseType
78
79// Error `code` strings the server returns. Stable across protocol
80// version 1, adding new codes is safe; renaming or removing one
81// is a protocol break. A deferred call may also fail with a code its
82// target picked (IpcPendingReply::fail), which is not in this list.
83namespace ErrorCode {
84constexpr auto NoSuchTarget = "NO_SUCH_TARGET";
85constexpr auto NoSuchFn = "NO_SUCH_FN";
86constexpr auto NoSuchSignal = "NO_SUCH_SIGNAL";
87constexpr auto NoSuchSubscription = "NO_SUCH_SUBSCRIPTION";
88constexpr auto InvalidArg = "INVALID_ARG";
89constexpr auto InvocationFailed = "INVOCATION_FAILED";
90constexpr auto MalformedRequest = "MALFORMED_REQUEST";
91// The call ran and failed: the target called
92// IpcCallContext::sendErrorReply, or IpcPendingReply::fail without a
93// code. Also a deferral past the router's cap on waiting deferred calls.
94constexpr auto CallFailed = "CALL_FAILED";
95// The target deferred the call's reply and dropped the IpcPendingReply
96// without answering it.
97constexpr auto CallAbandoned = "CALL_ABANDONED";
98} // namespace ErrorCode
99
100// Parsed request shape, populated by parseRequest from a single
101// JSON line. All fields are optional and only set when present;
102// callers should inspect type and validate the corresponding fields.
103struct PHOSPHORIPC_EXPORT Request
104{
105 QString type;
106 qint64 id = 0;
107 QString target;
108 QString fn;
109 // Spelled `signalName` (not just `signal`) because `signal` is
110 // a Qt macro that vanishes under `-DQT_NO_KEYWORDS` builds; the
111 // rename keeps the field accessible regardless of keyword mode
112 // and avoids confusing Qt-pseudo-keyword shadowing.
113 QString signalName;
114 qint64 subscriptionId = 0;
115 QVariantList args;
116};
117
118// Parse one NDJSON line into a Request. Returns std::nullopt and
119// populates parseError on malformed input: invalid JSON, missing
120// required `type` field, missing per-type required fields (`target`
121// for call/schema/subscribe, `fn` for call, `signal` for subscribe,
122// non-zero `subscriptionId` for unsubscribe), an `id` or
123// `subscriptionId` that isn't a finite integer in the range
124// exactly representable as both a JSON double and a qint64, or an
125// `args` value that isn't an array of size ≤ 4096. Callers are
126// expected to reply with a MALFORMED_REQUEST error.
127[[nodiscard]] PHOSPHORIPC_EXPORT std::optional<Request> parseRequest(const QByteArray& line, QString* parseError);
128
129// Encoders, build the QJsonObject body for each response variant.
130// The router serialises the object to bytes via writeLine() below.
131[[nodiscard]] PHOSPHORIPC_EXPORT QJsonObject buildReply(qint64 id, const QJsonValue& result);
132[[nodiscard]] PHOSPHORIPC_EXPORT QJsonObject buildEvent(qint64 subscriptionId, const QJsonValue& args);
133// An event addressed to one connection, not to a subscription: named by
134// `target` and `signal` (IpcRouter::sendEvent).
135[[nodiscard]] PHOSPHORIPC_EXPORT QJsonObject buildEvent(const QString& target, const QString& signalName,
136 const QJsonValue& args);
137[[nodiscard]] PHOSPHORIPC_EXPORT QJsonObject buildError(qint64 id, const QString& code, const QString& message,
138 const QJsonObject& detail = {});
139
140// Serialise a QJsonObject to a single NDJSON line, compact JSON
141// followed by '\n'. Output is UTF-8 bytes ready to push into a
142// QLocalSocket.
143[[nodiscard]] PHOSPHORIPC_EXPORT QByteArray writeLine(const QJsonObject& obj);
144
145// Convert a QVariant to a JSON value. Recursive on QVariantList /
146// QVariantMap. Numeric / bool / string / list / map types map
147// naturally; QJsonValue / QJsonObject / QJsonArray pass through;
148// invalid QVariant maps to null; any other metatype degrades to
149// the toString() representation. Shared between the router's
150// call-return path and IpcTarget's emitEvent broadcast path so
151// the wire JSON shape stays identical across the two.
152[[nodiscard]] PHOSPHORIPC_EXPORT QJsonValue variantToJson(const QVariant& v);
153
154} // namespace PhosphorIpc
Definition IpcProtocol.h:83
constexpr auto InvocationFailed
Definition IpcProtocol.h:89
constexpr auto CallFailed
Definition IpcProtocol.h:94
constexpr auto NoSuchSignal
Definition IpcProtocol.h:86
constexpr auto NoSuchSubscription
Definition IpcProtocol.h:87
constexpr auto CallAbandoned
Definition IpcProtocol.h:97
constexpr auto InvalidArg
Definition IpcProtocol.h:88
constexpr auto NoSuchFn
Definition IpcProtocol.h:85
constexpr auto MalformedRequest
Definition IpcProtocol.h:90
constexpr auto NoSuchTarget
Definition IpcProtocol.h:84
Definition IpcProtocol.h:46
constexpr auto Id
Definition IpcProtocol.h:48
constexpr auto Code
Definition IpcProtocol.h:55
constexpr auto Detail
Definition IpcProtocol.h:57
constexpr auto Fn
Definition IpcProtocol.h:50
constexpr auto Result
Definition IpcProtocol.h:54
constexpr auto Message
Definition IpcProtocol.h:56
constexpr auto Args
Definition IpcProtocol.h:51
constexpr auto Type
Definition IpcProtocol.h:47
constexpr auto SubscriptionId
Definition IpcProtocol.h:53
constexpr auto Signal
Definition IpcProtocol.h:52
constexpr auto Target
Definition IpcProtocol.h:49
Definition IpcProtocol.h:61
constexpr auto Call
Definition IpcProtocol.h:62
constexpr auto Subscribe
Definition IpcProtocol.h:65
constexpr auto Unsubscribe
Definition IpcProtocol.h:66
constexpr auto Schema
Definition IpcProtocol.h:64
constexpr auto List
Definition IpcProtocol.h:63
Definition IpcProtocol.h:70
constexpr auto Event
Definition IpcProtocol.h:75
constexpr auto Error
Definition IpcProtocol.h:76
constexpr auto Reply
Definition IpcProtocol.h:71
Definition IpcCallContext.h:10
PHOSPHORIPC_EXPORT QJsonObject buildReply(qint64 id, const QJsonValue &result)
PHOSPHORIPC_EXPORT QJsonObject buildError(qint64 id, const QString &code, const QString &message, const QJsonObject &detail={})
constexpr int ProtocolVersion
Definition IpcProtocol.h:34
PHOSPHORIPC_EXPORT QByteArray writeLine(const QJsonObject &obj)
PHOSPHORIPC_EXPORT QJsonObject buildEvent(qint64 subscriptionId, const QJsonValue &args)
PHOSPHORIPC_EXPORT std::optional< Request > parseRequest(const QByteArray &line, QString *parseError)
PHOSPHORIPC_EXPORT QJsonValue variantToJson(const QVariant &v)
Definition IpcProtocol.h:104
QString fn
Definition IpcProtocol.h:108
qint64 subscriptionId
Definition IpcProtocol.h:114
QString signalName
Definition IpcProtocol.h:113
QString type
Definition IpcProtocol.h:105
QVariantList args
Definition IpcProtocol.h:115
QString target
Definition IpcProtocol.h:107