include/pmcp/pmcp_rpc.h

filter: Statementstmt 97.9% 95 / 97 Branchbran 85.5% 65 / 76 Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 92.4% 160 / 173 CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« include/pmcp/pmcp_uri.h ↑ Summary include/pmcp/pmcp_page.h »
1 /* pmcp_rpc.h - JSON-RPC 2.0: decode, classify, encode, the envelope.
2 *
3 * Needs: pmcp_clos.h, pmcp_abi.h.
4 * Gives: pmcp_rpc_decode, pmcp_rpc_classify, pmcp_json, pmcp_rpc_result,
5 * pmcp_rpc_error, and the small builders pmcp_str and pmcp_bool.
6 *
7 * Bytes on the wire match Maat's (Maat/include/mt_mcp.h:208-248): canonical
8 * encoding, so keys are sorted and an envelope reads {"error"|"id","jsonrpc",
9 * "result"}, and the same lowercase messages. A client that talks to both sees
10 * the same framing.
11 */
12  
13 #ifndef PMCP_RPC_H
14 #define PMCP_RPC_H
15  
16 #define PMCP_PARSE (-32700)
17 #define PMCP_REQUEST (-32600)
18 #define PMCP_METHOD (-32601)
19 #define PMCP_PARAMS (-32602)
20 #define PMCP_INTERNAL (-32603)
21  
22 /* ---- decode -------------------------------------------------------------- */
23  
24 static SV *PMCP_DECODE = NULL; /* \&File::Raw::JSON::file_json_decode */
25  
26 /* BOOT, after pmcp_abi_boot has loaded File::Raw::JSON. */
27 46 static void pmcp_rpc_boot(pTHX)
28 {
29 46 CV *cv = get_cv("File::Raw::JSON::file_json_decode", 0);
30 46 ▶ if (!cv) croak(PMCP_DIST ": File::Raw::JSON has no file_json_decode");
Branch: 1 branch
BranchTrueFalseTotal
if (!cv) croak(PMCP_DIST ": File::Raw::JSON has no file_json_decode"); 0 46 46
31 46 PMCP_DECODE = newRV_inc((SV *)cv);
32 46 }
33  
34 /* Decode a body. Returns +1, or NULL when the bytes are not JSON.
35 *
36 * Through the XSUB under G_EVAL, never through the ABI's decode pointer. These
37 * bytes are the caller's, so a croak from the parser is normal operation here,
38 * and only a real G_EVAL frame unwinds the stacks a croak abandons. Trapping it
39 * with JMPENV_PUSH answers correctly and leaves the interpreter to die later in
40 * some loop it does not own (plan_maat_mcp 02, "panic: pp_iter"). */
41 606 static SV *pmcp_rpc_decode(pTHX_ SV *bytes)
42 {
43 606 SV *err = NULL;
44 SV *doc;
45 SV *arg[1];
46  
47 606 arg[0] = bytes;
48 606 doc = pmcp_call_sv(aTHX_ PMCP_DECODE, arg, 1, G_SCALAR, &err);
49 606 ▶ if (!doc) {
Branch: 1 branch
BranchTrueFalseTotal
if (!doc) { 11 595 606
50 11 SvREFCNT_dec(err);
51 11 return NULL;
52 }
53 595 return doc;
54 }
55  
56 /* ---- encode -------------------------------------------------------------- */
57  
58 /* Canonical JSON of a value this dist built. Returns +1.
59 *
60 * Through the ABI, with no G_EVAL, so only for values whose shape is known:
61 * the envelope, initialize, the frozen lists. A value an application handed
62 * back can hold anything, and goes through pmcp_json_trapped instead (05). */
63 657 static SV *pmcp_json(pTHX_ SV *value)
64 {
65 frj_opts o;
66 657 PMCP_FRJ->opts_init(&o);
67 657 o.canonical = 1;
68 657 return PMCP_FRJ->encode(aTHX_ value, &o);
69 }
70  
71 /* A new string SV with only the string slot: a version given as 1.10 in Perl
72 * goes out as "1.10" and not as the number 1.1. Returns +1. */
73 400 static SV *pmcp_str(pTHX_ SV *sv)
74 {
75 STRLEN l;
76 400 const char *p = SvPV_const(sv, l);
77 400 SV *out = newSVpvn(p, l);
78 400 ▶ if (SvUTF8(sv)) SvUTF8_on(out);
Branch: 1 branch
BranchTrueFalseTotal
if (SvUTF8(sv)) SvUTF8_on(out); 0 400 400
79 400 return out;
80 }
81  
82 /* A JSON boolean: frj encodes a reference to 1 or 0 as true or false. */
83 612 static SV *pmcp_bool(pTHX_ int b)
84 {
85 612 return newRV_noinc(newSViv(b ? 1 : 0));
86 }
87  
88 /* ---- the envelope -------------------------------------------------------- */
89  
90 /* The id as it was sent, encoded alone: 1 stays 1 and "1" stays "1". */
91 346 static void pmcp_cat_id(pTHX_ SV *out, SV *id)
92 {
93 346 ▶ if (!id || !SvOK(id)) {
Branch: 2 branches
BranchTrueFalseTotal
if (!id || !SvOK(id)) { 346 0 346
if (!id || !SvOK(id)) { 0 346 346
94 0 sv_catpvs(out, "null");
95 0 return;
96 }
97 {
98 346 SV *b = pmcp_json(aTHX_ id);
99 346 sv_catsv(out, b);
100 346 SvREFCNT_dec(b);
101 }
102 }
103  
104 /* {"id":ID,"jsonrpc":"2.0","result":RESULT}, with RESULT already encoded.
105 * Spliced rather than encoded whole so a frozen list (05) goes out as stored.
106 * The key order is the canonical one. Returns +1. */
107 346 static SV *pmcp_rpc_result_bytes(pTHX_ SV *id, SV *result_bytes)
108 {
109 346 SV *out = newSVpvs("{\"id\":");
110 346 pmcp_cat_id(aTHX_ out, id);
111 346 sv_catpvs(out, ",\"jsonrpc\":\"2.0\",\"result\":");
112 346 sv_catsv(out, result_bytes);
113 346 sv_catpvs(out, "}");
114 346 return out;
115 }
116  
117 /* The same, encoding RESULT (a value this dist built, or NULL for {}). Takes
118 * ownership of result. Returns +1. */
119 151 static SV *pmcp_rpc_result(pTHX_ SV *id, SV *result)
120 {
121 SV *bytes, *out;
122 151 ▶ if (!result) result = newRV_noinc((SV *)newHV());
Branch: 1 branch
BranchTrueFalseTotal
if (!result) result = newRV_noinc((SV *)newHV()); 0 151 151
123 151 bytes = pmcp_json(aTHX_ result);
124 151 SvREFCNT_dec(result);
125 151 out = pmcp_rpc_result_bytes(aTHX_ id, bytes);
126 151 SvREFCNT_dec(bytes);
127 151 return out;
128 }
129  
130 /* {"error":{"code":C,"data":D,"message":M},"id":ID,"jsonrpc":"2.0"}. Takes
131 * ownership of data, which may be NULL. Returns +1. */
132 160 static SV *pmcp_rpc_error(pTHX_ SV *id, int code, const char *msg, SV *data)
133 {
134 160 HV *r = newHV(), *e = newHV();
135 SV *rv, *out;
136  
137 160 (void)hv_stores(e, "code", newSViv(code));
138 160 (void)hv_stores(e, "message", newSVpv(msg, 0));
139 160 ▶ if (data) (void)hv_stores(e, "data", data);
Branch: 1 branch
BranchTrueFalseTotal
if (data) (void)hv_stores(e, "data", data); 31 129 160
140 160 (void)hv_stores(r, "error", newRV_noinc((SV *)e));
141 160 ▶ (void)hv_stores(r, "id", (id && SvOK(id)) ? newSVsv(id) : newSV(0));
Branch: 2 branches
BranchTrueFalseTotal
(void)hv_stores(r, "id", (id && SvOK(id)) ? newSVsv(id) : newSV(0)); 83 77 160
(void)hv_stores(r, "id", (id && SvOK(id)) ? newSVsv(id) : newSV(0)); 83 0 83
142 160 (void)hv_stores(r, "jsonrpc", newSVpvs("2.0"));
143 160 rv = newRV_noinc((SV *)r);
144 160 out = pmcp_json(aTHX_ rv);
145 160 SvREFCNT_dec(rv);
146 160 return out;
147 }
148  
149 /* ---- classification ------------------------------------------------------ */
150  
151 enum pmcp_kind {
152 PMCP_K_INVALID = 0, /* answer err_code, with the id when it is usable */
153 PMCP_K_REQUEST, /* method and id: owed an answer */
154 PMCP_K_NOTIFY, /* method and no id: owed nothing */
155 PMCP_K_RESPONSE /* result or error and an id: owed nothing */
156 };
157  
158 typedef struct {
159 enum pmcp_kind kind;
160 int err_code; /* for PMCP_K_INVALID */
161 const char *err_msg;
162 SV *id; /* borrowed from the document, or NULL */
163 const char *method; /* borrowed */
164 STRLEN mlen;
165 HV *params; /* borrowed, NULL when absent */
166 } pmcp_msg;
167  
168 /* A usable id: a string, or an integer. Not null, not a float, not a boolean,
169 * object or array. MCP narrows JSON-RPC here: an id MUST NOT be null. */
170 750 static int pmcp_id_ok(SV *id)
171 {
172 750 ▶ if (!id || !SvOK(id) || SvROK(id)) return 0;
Branch: 3 branches
BranchTrueFalseTotal
if (!id || !SvOK(id) || SvROK(id)) return 0; 750 0 750
if (!id || !SvOK(id) || SvROK(id)) return 0; 746 4 750
if (!id || !SvOK(id) || SvROK(id)) return 0; 4 742 746
173 742 ▶ if (SvPOK(id)) return 1;
Branch: 1 branch
BranchTrueFalseTotal
if (SvPOK(id)) return 1; 34 708 742
174 708 ▶ if (SvIOK(id) && !SvNOK(id)) return 1;
Branch: 2 branches
BranchTrueFalseTotal
if (SvIOK(id) && !SvNOK(id)) return 1; 705 3 708
if (SvIOK(id) && !SvNOK(id)) return 1; 705 0 705
175 3 return 0;
176 }
177  
178 /* A plain string: not a reference, not a number. */
179 1856 static int pmcp_is_str(SV *sv)
180 {
181 1856 ▶ return sv && SvOK(sv) && !SvROK(sv) && SvPOK(sv);
Branch: 4 branches
BranchTrueFalseTotal
return sv && SvOK(sv) && !SvROK(sv) && SvPOK(sv); 1856 0 1856
return sv && SvOK(sv) && !SvROK(sv) && SvPOK(sv); 1856 0 1856
return sv && SvOK(sv) && !SvROK(sv) && SvPOK(sv); 1853 3 1856
return sv && SvOK(sv) && !SvROK(sv) && SvPOK(sv); 1849 4 1853
182 }
183  
184 769 static void pmcp_rpc_classify(pTHX_ SV *doc, pmcp_msg *m)
185 {
186 HV *h;
187 SV **jv, **mv, **iv, **pv;
188  
189 769 Zero(m, 1, pmcp_msg);
190 769 m->kind = PMCP_K_INVALID;
191 769 m->err_code = PMCP_REQUEST;
192 769 m->err_msg = "invalid request";
193  
194 /* An array is a 2025-03-26 batch. Later versions removed them, and this
195 * server says so rather than serving half of one (16). */
196 769 ▶ if (pmcp_is_array(doc)) {
Branch: 1 branch
BranchTrueFalseTotal
if (pmcp_is_array(doc)) { 7 762 769
197 7 m->err_msg = "batches are not supported";
198 7 return;
199 }
200 762 ▶ if (!pmcp_is_hash(doc)) return;
Branch: 1 branch
BranchTrueFalseTotal
if (!pmcp_is_hash(doc)) return; 2 760 762
201 760 h = (HV *)SvRV(doc);
202  
203 760 iv = hv_fetchs(h, "id", 0);
204 760 ▶ if (iv && pmcp_id_ok(*iv)) m->id = *iv;
Branch: 2 branches
BranchTrueFalseTotal
if (iv && pmcp_id_ok(*iv)) m->id = *iv; 724 36 760
if (iv && pmcp_id_ok(*iv)) m->id = *iv; 714 10 724
205  
206 760 jv = hv_fetchs(h, "jsonrpc", 0);
207 1518 ▶ if (!jv || !pmcp_is_str(*jv) || !strEQ(SvPV_nolen(*jv), "2.0")) return;
Branch: 3 branches
BranchTrueFalseTotal
if (!jv || !pmcp_is_str(*jv) || !strEQ(SvPV_nolen(*jv), "2.0")) return; 759 1 760
if (!jv || !pmcp_is_str(*jv) || !strEQ(SvPV_nolen(*jv), "2.0")) return; 758 1 759
if (!jv || !pmcp_is_str(*jv) || !strEQ(SvPV_nolen(*jv), "2.0")) return; 2 756 758
208  
209 756 mv = hv_fetchs(h, "method", 0);
210 756 ▶ if (!mv) {
Branch: 1 branch
BranchTrueFalseTotal
if (!mv) { 8 748 756
211 /* A response to a request this server sent. None are sent in v1 (16),
212 * so one is accepted and dropped. */
213 8 ▶ if (iv && m->id && (hv_exists(h, "result", 6) || hv_exists(h, "error", 5)))
Branch: 4 branches
BranchTrueFalseTotal
if (iv && m->id && (hv_exists(h, "result", 6) || hv_exists(h, "error", 5))) 7 1 8
if (iv && m->id && (hv_exists(h, "result", 6) || hv_exists(h, "error", 5))) 7 0 7
if (iv && m->id && (hv_exists(h, "result", 6) || hv_exists(h, "error", 5))) 2 5 7
if (iv && m->id && (hv_exists(h, "result", 6) || hv_exists(h, "error", 5))) 1 1 2
214 6 m->kind = PMCP_K_RESPONSE;
215 8 return;
216 }
217 748 ▶ if (!pmcp_is_str(*mv)) return;
Branch: 1 branch
BranchTrueFalseTotal
if (!pmcp_is_str(*mv)) return; 2 746 748
218 746 m->method = SvPV_const(*mv, m->mlen);
219  
220 746 pv = hv_fetchs(h, "params", 0);
221 746 ▶ if (pv && SvOK(*pv)) {
Branch: 2 branches
BranchTrueFalseTotal
if (pv && SvOK(*pv)) { 608 138 746
if (pv && SvOK(*pv)) { 607 1 608
222 607 ▶ if (!pmcp_is_hash(*pv)) {
Branch: 1 branch
BranchTrueFalseTotal
if (!pmcp_is_hash(*pv)) { 5 602 607
223 5 ▶ if (iv) {
Branch: 1 branch
BranchTrueFalseTotal
if (iv) { 4 1 5
224 4 m->err_code = PMCP_PARAMS;
225 4 m->err_msg = "params must be an object";
226 }
227 1 else m->kind = PMCP_K_NOTIFY; /* owed nothing, even when wrong */
228 5 return;
229 }
230 602 m->params = (HV *)SvRV(*pv);
231 }
232  
233 741 ▶ if (!iv) { m->kind = PMCP_K_NOTIFY; return; }
Branch: 1 branch
BranchTrueFalseTotal
if (!iv) { m->kind = PMCP_K_NOTIFY; return; } 34 707 741
234 707 ▶ if (!m->id) return; /* an id that is not usable */
Branch: 1 branch
BranchTrueFalseTotal
if (!m->id) return; /* an id that is not usable */ 10 697 707
235 697 m->kind = PMCP_K_REQUEST;
236 }
237  
238 #endif /* PMCP_RPC_H */
« include/pmcp/pmcp_uri.h ↑ Summary include/pmcp/pmcp_page.h »