pbwire 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,746 @@
1
+ /*
2
+ * pbwire - a dependency-free Protobuf runtime in C with dynamic schema support.
3
+ *
4
+ * Schemas are built at runtime (see pbw_schema_*); messages are dynamic value
5
+ * trees (see pbw_message_*); wire encoding/decoding follows the standard
6
+ * Protobuf wire format (see pbw_encode / pbw_decode).
7
+ *
8
+ * Conventions:
9
+ * - Every pointer returned by this library is owned by the library unless
10
+ * documented otherwise; free with pbw_free() / pbw_message_free() /
11
+ * pbw_value_free().
12
+ * - Numeric values are stored as raw bit patterns: PBW_TYPE_FLOAT and
13
+ * PBW_TYPE_FIXED32/PBW_TYPE_SFIXED32 live in the low 32 bits,
14
+ * PBW_TYPE_DOUBLE and the 64-bit fixed types use all 64 bits. Signed
15
+ * types are sign extended.
16
+ * - Byte payloads are always NUL terminated so pbw_value_get_string() is safe
17
+ * on decoded string fields (the extra byte is not part of the field length).
18
+ * - No defaults are filled in: a field that was not present on the wire is
19
+ * simply absent (pbw_message_get() returns NULL). Explicit presence per field.
20
+ */
21
+ #ifndef PBWIRE_H
22
+ #define PBWIRE_H
23
+
24
+ #include <stddef.h>
25
+ #include <stdint.h>
26
+
27
+ /* The library is built with -fvisibility=hidden: everything declared here is
28
+ * exported, and the internal helpers (src/internal.h) stay out of the dynamic
29
+ * symbol table. An embedder can therefore not link against them by accident,
30
+ * and their names are free to change without an ABI break. */
31
+ #if defined(__GNUC__) || defined(__clang__)
32
+ #pragma GCC visibility push(default)
33
+ #endif
34
+
35
+ /* ABI version: bumped on every breaking change to the C ABI (removed or
36
+ * reordered exports, changed struct layouts visible to callers). Additive
37
+ * changes keep the number. The shared library SONAME carries the same
38
+ * number, so `libpbwire.so.1` and `PBW_ABI_VERSION == 1` always agree. */
39
+ #define PBW_ABI_VERSION 1
40
+
41
+ #ifdef __cplusplus
42
+ extern "C" {
43
+ #endif
44
+
45
+ /* Runtime view of PBW_ABI_VERSION, for bindings that dlopen the library. */
46
+ int pbw_abi_version(void);
47
+
48
+ typedef enum {
49
+ PBW_OK = 0,
50
+ PBW_ERR_INVALID = 1, /* malformed wire data or invalid argument */
51
+ PBW_ERR_NOMEM = 2, /* allocation failure */
52
+ PBW_ERR_NOT_FOUND = 3, /* unknown field number / name */
53
+ PBW_ERR_TYPE = 4, /* value does not match the field type */
54
+ PBW_ERR_LIMIT = 5, /* nesting or size limit exceeded */
55
+ PBW_ERR_REQUIRED = 6 /* a proto2 required field has no value */
56
+ } pbw_status;
57
+
58
+ /* Values match protobuf FieldDescriptorProto.Type numbering. */
59
+ typedef enum {
60
+ PBW_TYPE_DOUBLE = 1,
61
+ PBW_TYPE_FLOAT = 2,
62
+ PBW_TYPE_INT64 = 3,
63
+ PBW_TYPE_UINT64 = 4,
64
+ PBW_TYPE_INT32 = 5,
65
+ PBW_TYPE_FIXED64 = 6,
66
+ PBW_TYPE_FIXED32 = 7,
67
+ PBW_TYPE_BOOL = 8,
68
+ PBW_TYPE_STRING = 9,
69
+ PBW_TYPE_GROUP = 10,
70
+ PBW_TYPE_MESSAGE = 11,
71
+ PBW_TYPE_BYTES = 12,
72
+ PBW_TYPE_UINT32 = 13,
73
+ PBW_TYPE_ENUM = 14,
74
+ PBW_TYPE_SFIXED32 = 15,
75
+ PBW_TYPE_SFIXED64 = 16,
76
+ PBW_TYPE_SINT32 = 17,
77
+ PBW_TYPE_SINT64 = 18
78
+ } pbw_type;
79
+
80
+ /* Values match protobuf FieldDescriptorProto.Label numbering. */
81
+ typedef enum {
82
+ PBW_LABEL_OPTIONAL = 1,
83
+ PBW_LABEL_REQUIRED = 2,
84
+ PBW_LABEL_REPEATED = 3
85
+ } pbw_label;
86
+
87
+ typedef enum {
88
+ PBW_VALUE_UINT = 0, /* any numeric type, raw bit pattern */
89
+ PBW_VALUE_BYTES = 1, /* string or bytes */
90
+ PBW_VALUE_MESSAGE = 2,
91
+ PBW_VALUE_LIST = 3 /* repeated field storage */
92
+ } pbw_value_kind;
93
+
94
+ typedef struct pbw_schema pbw_schema;
95
+ typedef struct pbw_ctx pbw_ctx;
96
+ typedef struct pbw_descriptor pbw_descriptor;
97
+ typedef struct pbw_field pbw_field;
98
+ typedef struct pbw_value pbw_value;
99
+ typedef struct pbw_message pbw_message;
100
+ typedef struct pbw_service pbw_service;
101
+ typedef struct pbw_method pbw_method;
102
+
103
+ /* ---------------------------------------------------------------- schema */
104
+
105
+ pbw_schema *pbw_schema_new(void);
106
+ void pbw_schema_free(pbw_schema *schema);
107
+
108
+ /* Create a message or enum descriptor. Names must be unique within a schema. */
109
+ pbw_descriptor *pbw_schema_add_message(pbw_schema *schema, const char *name);
110
+ pbw_descriptor *pbw_schema_add_enum(pbw_schema *schema, const char *name);
111
+ pbw_descriptor *pbw_schema_find(const pbw_schema *schema, const char *name);
112
+
113
+ /* Dialect for the descriptors added afterwards: 1 = proto3/editions semantics
114
+ * (open enums, no required checks; the default), 0 = proto2 semantics (closed
115
+ * enums, `required` fields validated when decoding). A descriptor set sets this
116
+ * per file on its own, so this is only needed for hand-built schemas. */
117
+ void pbw_schema_set_proto3(pbw_schema *schema, int proto3);
118
+
119
+ /* Append an enum value. Enum descriptors are only usable after
120
+ * pbw_schema_link(). Returns PBW_OK, PBW_ERR_INVALID for a bad descriptor
121
+ * or a frozen schema, PBW_ERR_NOMEM when the value cannot be stored. */
122
+ pbw_status pbw_enum_add_value(pbw_descriptor *enum_desc, const char *name,
123
+ int32_t number);
124
+ int pbw_enum_find_name(const pbw_descriptor *enum_desc, int32_t number,
125
+ const char **name);
126
+ int pbw_enum_find_value(const pbw_descriptor *enum_desc, const char *name,
127
+ int32_t *number);
128
+
129
+ /* Append a field. Field numbers must be unique within the message, and every
130
+ * field must be added before the first successful pbw_schema_link(): the layout
131
+ * (and with it the value slots of every existing message) freezes then, so a
132
+ * later add fails and returns NULL. */
133
+ pbw_field *pbw_message_add_field(pbw_descriptor *msg, const char *name,
134
+ uint32_t number, pbw_type type,
135
+ pbw_label label);
136
+ /* Append an extension field to the message it extends. Only the number must be
137
+ * unique: extensions from different scopes may share a name, so they are found
138
+ * by number (pbw_descriptor_find_field), not by name. */
139
+ pbw_field *pbw_message_add_extension(pbw_descriptor *msg, const char *name,
140
+ uint32_t number, pbw_type type,
141
+ pbw_label label);
142
+
143
+ /* Point a MESSAGE/ENUM field at another descriptor by name; resolved by
144
+ * pbw_schema_link(). */
145
+ void pbw_field_set_type_name(pbw_field *field, const char *type_name);
146
+ /* Dotted full name of an extension field ("pkg.Ext"), used inside brackets
147
+ * by the text format. The loader sets this from the declaring scope; call it
148
+ * for hand-built extensions that must parse `[pkg.Ext]` text. */
149
+ void pbw_field_set_full_name(pbw_field *field, const char *full_name);
150
+ /* Emit repeated numeric fields packed (proto3 default). */
151
+ void pbw_field_set_packed(pbw_field *field, int packed);
152
+ /* Mark a message as a map entry (MessageOptions.map_entry): JSON prints it
153
+ * as an object instead of an array of entries. The loader sets this from
154
+ * the descriptor; call it for hand-built map entries. */
155
+ void pbw_descriptor_set_map_entry(pbw_descriptor *msg);
156
+ /* 1-based oneof group index; 0 means the field is not in a oneof. */
157
+ void pbw_field_set_oneof(pbw_field *field, uint32_t oneof_index);
158
+
159
+ /* Resolve type names, sort fields by number and build lookup tables. Idempotent
160
+ * while no field is added; the first success freezes the field layout, so
161
+ * create messages and set values only after it returns PBW_OK. Link once
162
+ * before sharing the schema across threads: add/link while another thread
163
+ * reads it races on the lookup tables. */
164
+ pbw_status pbw_schema_link(pbw_schema *schema);
165
+ /* Last link failure reason (empty when the last link succeeded). */
166
+ const char *pbw_schema_error(const pbw_schema *schema);
167
+
168
+ /* Load a standard FileDescriptorSet (protoc --descriptor_set_out, buf, ...)
169
+ * into a new schema, so a schema can come from a .proto without generated code.
170
+ * Every referenced type must be present in the set (use --include_imports).
171
+ * Descriptors are named fully qualified without the leading dot:
172
+ * "pkg.Outer.Inner". Field type names resolve the same way.
173
+ * *out is always written; on failure it holds the partially built schema so
174
+ * pbw_schema_error() explains why, and the caller frees it as usual. */
175
+ pbw_status pbw_descriptor_set_load(const void *data, size_t len,
176
+ pbw_schema **out);
177
+
178
+ const char *pbw_descriptor_name(const pbw_descriptor *desc);
179
+ int pbw_descriptor_is_enum(const pbw_descriptor *desc);
180
+ /* Nonzero when the descriptor is a map entry (MessageOptions.map_entry). */
181
+ int pbw_descriptor_is_map_entry(const pbw_descriptor *desc);
182
+ /* 1 for proto3/editions semantics (open enums, no `required` fields), 0 for
183
+ * proto2 syntax. Decides whether an unknown enum number stays in the field or
184
+ * moves to the unknown fields, so a decoder that materializes values itself
185
+ * needs it to match the reference parsers. */
186
+ int pbw_descriptor_is_proto3(const pbw_descriptor *desc);
187
+ size_t pbw_descriptor_field_count(const pbw_descriptor *desc);
188
+ const pbw_field *pbw_descriptor_field_at(const pbw_descriptor *desc,
189
+ size_t index);
190
+ const pbw_field *pbw_descriptor_find_field(const pbw_descriptor *desc,
191
+ uint32_t number);
192
+ const pbw_field *pbw_descriptor_find_field_name(const pbw_descriptor *desc,
193
+ const char *name);
194
+
195
+ const char *pbw_field_name(const pbw_field *field);
196
+ /* Services: loaded from a FileDescriptorSet, queryable for routing. The
197
+ * core does no RPC; a transport (gRPC, Twirp, plain HTTP) uses these to
198
+ * resolve method names to input/output types. Services live in the schema
199
+ * and die with it. Hand-built schemas carry no services. */
200
+ size_t pbw_schema_service_count(const pbw_schema *schema);
201
+ const pbw_service *pbw_schema_service_at(const pbw_schema *schema,
202
+ size_t index);
203
+ const pbw_service *pbw_schema_service_find(const pbw_schema *schema,
204
+ const char *name);
205
+ /* Fully qualified without the leading dot ("pkg.Service"), like descriptors. */
206
+ const char *pbw_service_name(const pbw_service *svc);
207
+ size_t pbw_service_method_count(const pbw_service *svc);
208
+ const pbw_method *pbw_service_method_at(const pbw_service *svc, size_t index);
209
+ const pbw_method *pbw_service_method_find(const pbw_service *svc,
210
+ const char *name);
211
+ const char *pbw_method_name(const pbw_method *method);
212
+ /* Fully qualified input/output message names, without the leading dot. */
213
+ const char *pbw_method_input_type(const pbw_method *method);
214
+ const char *pbw_method_output_type(const pbw_method *method);
215
+ /* Resolve a method to its input/output descriptors for routing: finds
216
+ * service `service`, then method `method`, then both message types by the
217
+ * method's input/output names. A transport (gRPC, Twirp, plain HTTP) decodes
218
+ * with *in_desc and encodes with *out_desc; the core still does no RPC.
219
+ * NULL for any missing piece, PBW_ERR_INVALID when anything is unknown. */
220
+ pbw_status pbw_service_resolve(const pbw_schema *schema, const char *service,
221
+ const char *method,
222
+ const pbw_descriptor **in_desc,
223
+ const pbw_descriptor **out_desc);
224
+ /* Well-known-type helpers over the dynamic API. The caller loads the
225
+ * descriptors (google/protobuf/any.proto etc. via a FileDescriptorSet);
226
+ * these only read/write fields 1 and 2, so a hand-built mirror with the
227
+ * same numbers works too. The core never special-cases WKTs elsewhere. */
228
+ /* Pack payload (already encoded bytes of the message named by type_url, e.g.
229
+ * "type.googleapis.com/pkg.Msg") into a new google.protobuf.Any tree. */
230
+ pbw_status pbw_any_pack(const pbw_descriptor *any_desc, const char *type_url,
231
+ const void *payload, size_t len, pbw_message **out);
232
+ /* type_url (field 1) of an Any tree, or NULL when absent. Owned by the tree. */
233
+ const char *pbw_any_type_url(const pbw_message *any_msg);
234
+ /* value bytes (field 2) of an Any tree; *len is 0 and NULL returns when
235
+ * absent. Owned by the tree. */
236
+ const void *pbw_any_payload(const pbw_message *any_msg, size_t *len);
237
+ /* google.protobuf.Timestamp / Duration as milliseconds: field 1 (seconds,
238
+ * int64) and field 2 (nanos, int32); nanos must be within +/-999,999,999.
239
+ * PBW_ERR_INVALID on out-of-range nanos or a missing seconds field,
240
+ * PBW_ERR_LIMIT when seconds overflow int64 milliseconds. */
241
+ pbw_status pbw_timestamp_to_millis(const pbw_message *ts, int64_t *out);
242
+ pbw_status pbw_duration_to_millis(const pbw_message *dur, int64_t *out);
243
+ /* The pack direction: a new Timestamp/Duration tree holding ms. Nanos keep
244
+ * the millisecond remainder, so the value round-trips through *_to_millis. */
245
+ pbw_status pbw_timestamp_from_millis(const pbw_descriptor *ts_desc, int64_t ms,
246
+ pbw_message **out);
247
+ pbw_status pbw_duration_from_millis(const pbw_descriptor *dur_desc, int64_t ms,
248
+ pbw_message **out);
249
+ /* google.protobuf.FieldMask paths (field 1, repeated string) without
250
+ * materializing the list: count and indexed access, NULL past the end. */
251
+ size_t pbw_fieldmask_path_count(const pbw_message *mask);
252
+ const char *pbw_fieldmask_path_at(const pbw_message *mask, size_t index);
253
+ /* Streaming flags from MethodDescriptorProto; both 0 is unary. */
254
+ int pbw_method_client_streaming(const pbw_method *method);
255
+ int pbw_method_server_streaming(const pbw_method *method);
256
+ /* proto2 default as written in the .proto, or NULL when the field has none. */
257
+ const char *pbw_field_default_value(const pbw_field *field);
258
+ /* 1 when the field was declared as an extension of its message. */
259
+ int pbw_field_is_extension(const pbw_field *field);
260
+ uint32_t pbw_field_number(const pbw_field *field);
261
+ pbw_type pbw_field_type(const pbw_field *field);
262
+ pbw_label pbw_field_label(const pbw_field *field);
263
+ int pbw_field_is_packed(const pbw_field *field);
264
+ /* 1 when a decoded value of this field must be valid UTF-8, i.e. the reference
265
+ * implementation's rule: a `string` field whose utf8_validation resolves to
266
+ * VERIFY (proto3 and edition 2023+ files by default, proto2 never unless a
267
+ * FeatureSet says otherwise). pbw_decode() rejects such a value with
268
+ * PBW_ERR_INVALID instead of storing bytes the reference would refuse; `bytes`
269
+ * fields and proto2 strings stay unchecked, exactly like the reference. */
270
+ int pbw_field_requires_utf8_validation(const pbw_field *field);
271
+ /* Structural UTF-8 check: 1 when data is valid UTF-8, 0 for overlong forms,
272
+ * surrogates and values past U+10FFFF. The same check decode() applies to a
273
+ * field whose utf8_validation resolves to VERIFY, and that the text/JSON
274
+ * parsers apply to every string they accept; bindings that validate on their
275
+ * own (a host runtime that decodes strings itself) should use this one so the
276
+ * rule stays single-sourced. */
277
+ int pbw_utf8_valid(const uint8_t *data, size_t len);
278
+ uint32_t pbw_field_oneof_index(const pbw_field *field);
279
+ const pbw_descriptor *pbw_field_message_type(const pbw_field *field);
280
+
281
+ /* --------------------------------------------------------------- message */
282
+
283
+ /* A message keeps pointing at its descriptor: the schema must outlive it. The
284
+ * descriptor must be linked (pbw_schema_link() returned PBW_OK), because field
285
+ * lookup relies on the number-sorted field array the link builds. */
286
+ pbw_message *pbw_message_new(const pbw_descriptor *desc);
287
+ /* Frees a message the caller owns and everything under it. A submessage
288
+ * handed out by a parent (pbw_message_set_message(), a decoded tree) is owned
289
+ * by that parent, so freeing it here is a no-op, like arena memory. */
290
+ void pbw_message_free(pbw_message *msg);
291
+ const pbw_descriptor *pbw_message_descriptor(const pbw_message *msg);
292
+ /* Wire length this tree was decoded from, 0 when it was built by hand. A
293
+ * buffer-size hint that needs no invalidation: mutation makes it an
294
+ * underestimate, which the encoder handles by growing. */
295
+ size_t pbw_message_wire_size(const pbw_message *msg);
296
+ /* Exact number of bytes pbw_encode() writes for this tree: one walk over the
297
+ * present values, no allocation, no bytes written. For callers that must know
298
+ * the length before encoding (a length-prefixed frame, a pre-sized buffer)
299
+ * this costs less than encoding twice. Deterministic encoding produces the
300
+ * same length. PBW_ERR_LIMIT when nesting exceeds PBW_MAX_DEPTH, PBW_ERR_INVALID
301
+ * on a NULL submessage or a message retired by a later schema change; *len is
302
+ * 0 on every failure. */
303
+ pbw_status pbw_message_encoded_size(const pbw_message *msg, size_t *len);
304
+ /* Slack pbw_encode_to() needs past pbw_message_encoded_size(): the writer
305
+ * reserves tag/varint room upfront, so `size + PBW_ENCODE_SLACK` is the
306
+ * smallest cap guaranteed to fit, while `size` alone may be rejected. */
307
+ #define PBW_ENCODE_SLACK 12
308
+
309
+ /* Present value of a field, or NULL. Repeated fields expose a
310
+ * PBW_VALUE_LIST. */
311
+ pbw_value *pbw_message_get(const pbw_message *msg, uint32_t number);
312
+ /* Same as pbw_message_get() for an already-resolved field of the message's
313
+ * descriptor (NULL when it belongs elsewhere); skips the number lookup for
314
+ * hot reflection loops that cached the pointer. Resolve the pointer again
315
+ * after any add or link: an add may move the field array and the link sorts
316
+ * it, so a cached pointer may name another field (use the number then). */
317
+ pbw_value *pbw_message_get_field(const pbw_message *msg,
318
+ const pbw_field *field);
319
+ /* Number of fields with a value. */
320
+ size_t pbw_message_field_count(const pbw_message *msg);
321
+ /* Present fields in field-index order: fills up to cap (fnum, value) pairs
322
+ * and returns how many were written. Lets hot reflection loops visit only
323
+ * what the wire carried instead of probing every schema field. */
324
+ size_t pbw_message_present_list(const pbw_message *msg, uint32_t *fnums,
325
+ const pbw_value **values, size_t cap);
326
+ /* Reflection over present fields; returns NULL past the end. */
327
+ const pbw_field *pbw_message_field_at(const pbw_message *msg, size_t index,
328
+ pbw_value **value);
329
+ /* 0 when a proto2 `required` field (recursively, through submessages) has no
330
+ * value. pbw_decode() already rejects such data the way the reference parser
331
+ * does; this is for a tree you built yourself, which pbw_encode() writes as it
332
+ * stands (the reference serializer does the same). Always 1 for proto3
333
+ * messages that contain no proto2 submessage. */
334
+ int pbw_message_is_initialized(const pbw_message *msg);
335
+ /* Drop a field value (and, for a oneof, the group case). A submessage the
336
+ * field owned is released with it; one that lives in the tree's arena
337
+ * survives the release unowned, so it can be stored into another field. While
338
+ * detached it rejects stores (nothing would release what it grew there) and
339
+ * becomes writable again once a tree owns it. */
340
+ void pbw_message_clear(pbw_message *msg, uint32_t number);
341
+
342
+ /* Unknown fields kept from decoding, as raw wire bytes (each item is its
343
+ * tag followed by its payload), in wire order. Empty when nothing unknown
344
+ * was seen. The bytes stay owned by the message. */
345
+ size_t pbw_message_unknown_len(const pbw_message *msg);
346
+ const uint8_t *pbw_message_unknown_bytes(const pbw_message *msg);
347
+ /* Append raw unknown-field bytes (tag + payload per item, as produced by
348
+ * pbw_message_unknown_bytes). Fails on context-owned read-only messages. */
349
+ pbw_status pbw_message_add_unknown_bytes(pbw_message *msg, const void *data,
350
+ size_t len);
351
+
352
+ /* Store a value: appends for repeated fields, replaces otherwise. Takes
353
+ * ownership of value on success only. Values owned by another message (see
354
+ * pbw_message_get()) are rejected with PBW_ERR_INVALID; build a fresh value
355
+ * instead. A message built with pbw_message_new_ctx() only accepts values
356
+ * built with the matching pbw_value_new_*_ctx() constructor (also
357
+ * PBW_ERR_INVALID): the context arena frees by reset, so it cannot own a heap
358
+ * payload. A plain-decoded tree accepts both. A message value must be able to
359
+ * die with the tree that takes it: it shares this tree's arena, or it owns an
360
+ * arena this tree releases (an adopted pbw_decode() root); a message from
361
+ * another context's arena is rejected the same way. A message that would
362
+ * become its own ancestor (its subtree already holds this message) is
363
+ * refused too, since a later clear() or free() would release the arena it
364
+ * is walking inside. */
365
+ pbw_status pbw_message_set(pbw_message *msg, uint32_t number, pbw_value *value);
366
+ /* Same as pbw_message_set() for an already-resolved field of the message's
367
+ * descriptor (PBW_ERR_INVALID when it belongs elsewhere); skips the number
368
+ * lookup for hot build loops that cached the pointer. Same caching rule as
369
+ * pbw_message_get_field(): re-resolve after any add or link. */
370
+ pbw_status pbw_message_set_field(pbw_message *msg, const pbw_field *field,
371
+ pbw_value *value);
372
+ /* Create (or return the existing) nested message value for a MESSAGE field. */
373
+ pbw_message *pbw_message_set_message(pbw_message *msg, uint32_t number);
374
+ /* Build a message tree in a context's arena for pbw_encode_ctx(): steady use
375
+ * stops calling malloc after the first few messages. The tree is mutable
376
+ * until the next pbw_decode_ctx() on the same context seals it; reset the
377
+ * context before each build or decode. Values are built with the
378
+ * pbw_value_new_*_ctx() constructors below so every payload lives in the
379
+ * same arena and dies with the reset; a heap value (pbw_value_new_string(),
380
+ * ...) is rejected with PBW_ERR_INVALID because the reset could not free it. */
381
+ pbw_message *pbw_message_new_ctx(pbw_ctx *ctx, const pbw_descriptor *desc);
382
+
383
+ /* ----------------------------------------------------------------- value */
384
+
385
+ pbw_value *pbw_value_new_uint(uint64_t bits);
386
+ pbw_value *pbw_value_new_int(int64_t value);
387
+ pbw_value *pbw_value_new_bool(int value);
388
+ pbw_value *pbw_value_new_float(float value);
389
+ pbw_value *pbw_value_new_double(double value);
390
+ pbw_value *pbw_value_new_bytes(const void *data, size_t len);
391
+ pbw_value *pbw_value_new_string(const char *str);
392
+ pbw_value *pbw_value_new_message(pbw_message *msg); /* takes ownership of msg */
393
+ /* Arena twins of the constructors above, for trees built with
394
+ * pbw_message_new_ctx(): payload bytes are copied into the context so the
395
+ * tree never points at caller memory. NULL data zero-fills the buffer for
396
+ * the caller to fill, read back via pbw_value_get_bytes() (a plain
397
+ * pbw_value_new_bytes(NULL, len) does the same). All scalars share the uint
398
+ * constructor (float/double/int/bool pass their bit pattern, like the plain
399
+ * pbw_value_new_int/bool/float/double do). */
400
+ pbw_value *pbw_value_new_uint_ctx(pbw_ctx *ctx, uint64_t bits);
401
+ pbw_value *pbw_value_new_bytes_ctx(pbw_ctx *ctx, const void *data, size_t len);
402
+ /* Frees a value created by pbw_value_new*(). Values owned by a message (from
403
+ * pbw_message_get(), pbw_value_at(), ...) are released with it: this call is a
404
+ * no-op on them. */
405
+ void pbw_value_free(pbw_value *value);
406
+
407
+ pbw_value_kind pbw_value_get_kind(const pbw_value *value);
408
+ uint64_t pbw_value_get_uint(const pbw_value *value);
409
+ int64_t pbw_value_get_int(const pbw_value *value);
410
+ int32_t pbw_value_get_int32(const pbw_value *value);
411
+ uint32_t pbw_value_get_uint32(const pbw_value *value);
412
+ int pbw_value_get_bool(const pbw_value *value);
413
+ float pbw_value_get_float(const pbw_value *value);
414
+ double pbw_value_get_double(const pbw_value *value);
415
+ const void *pbw_value_get_bytes(const pbw_value *value, size_t *len);
416
+ const char *pbw_value_get_string(const pbw_value *value);
417
+ pbw_message *pbw_value_get_message(const pbw_value *value);
418
+ size_t pbw_value_count(const pbw_value *value);
419
+ pbw_value *pbw_value_at(const pbw_value *value, size_t index);
420
+
421
+ /* -------------------------------------------------------------- workspace */
422
+
423
+ /*
424
+ * A context owns a bump allocator and a reusable encode buffer, so a program
425
+ * that decodes or encodes in a loop stops calling malloc after the first few
426
+ * messages. One context per thread/goroutine; never share one concurrently.
427
+ *
428
+ * Messages decoded with a context live in its allocator:
429
+ * - pbw_message_free() on them is a no-op (they die with pbw_ctx_reset)
430
+ * - they are read-only: pbw_message_set/set_message fail, clear does nothing
431
+ * - pbw_ctx_reset() invalidates every message decoded with it so far
432
+ * Plain pbw_decode()/pbw_encode() allocate one block per call instead (see
433
+ * below), so they need no workspace at all.
434
+ */
435
+ pbw_ctx *pbw_ctx_new(void);
436
+ /* Same context on caller memory: the handle, its arena and the arena's one
437
+ * chunk all live in mem, so the context never allocates and closing it never
438
+ * frees (nothing is owned). mem must be 8-byte aligned and len must cover the
439
+ * handle plus a chunk header plus room for one allocation; NULL when it is not. An allocation that does not fit returns PBW_ERR_NOMEM from decode and
440
+ * PBW_ERR_LIMIT from pbw_encode_to: the block is the hard cap, so a steady
441
+ * workload never calls malloc. pbw_encode_ctx() needs a growable buffer and
442
+ * reports PBW_ERR_NOMEM here; use pbw_encode_to() instead. */
443
+ pbw_ctx *pbw_ctx_new_mem(void *mem, size_t len);
444
+ void pbw_ctx_free(pbw_ctx *ctx);
445
+ /* Opaque binding slot, e.g. the language binding's per-thread state.
446
+ * Untouched by the core (reads, writes, reset and pooling all preserve
447
+ * it); freed with the context. */
448
+ void pbw_ctx_set_user(pbw_ctx *ctx, void *user);
449
+ void *pbw_ctx_user(const pbw_ctx *ctx);
450
+ /* Release every allocation made since the last reset, keeping the buffers.
451
+ * Every message built or decoded with this context dies here too: touching
452
+ * one afterwards reads whatever the next user of the chunk wrote. */
453
+ void pbw_ctx_reset(pbw_ctx *ctx);
454
+ /* Max bytes the context keeps resident across resets (decode arena chunks +
455
+ * encode buffer), default 1 MiB. Single allocations above it bypass the
456
+ * reusable chunks and are freed on reset, so one outlier never pins the
457
+ * context. 0 keeps nothing: every reset frees everything, like the plain
458
+ * functions but through the context API. Applies lazily at the next reset. */
459
+ void pbw_ctx_set_retain_cap(pbw_ctx *ctx, size_t cap);
460
+
461
+ typedef struct pbw_pool pbw_pool;
462
+
463
+ /* Bounded freelist of contexts: acquire instead of pbw_ctx_new, release
464
+ * instead of pbw_ctx_reset/pbw_ctx_free. A released context is already
465
+ * reset, so the next acquire can use it directly; releases past max_idle
466
+ * are freed. Unsynchronized: one pool per worker thread, never shared
467
+ * concurrently (this keeps the core dependency-free). Allocation is lazy;
468
+ * steady use then stops calling malloc.
469
+ *
470
+ * retain_cap is stamped on contexts the pool creates (0 = the 1 MiB
471
+ * default, like the zero-means-default pbw_limits fields); max_idle 0
472
+ * keeps nothing and the pool degenerates to new/free. Releasing a context
473
+ * whose retain cap the caller changed keeps that cap. */
474
+ pbw_pool *pbw_pool_new(size_t max_idle, size_t retain_cap);
475
+ void pbw_pool_free(pbw_pool *pool);
476
+ /* Exclusive use until released; NULL when pool is NULL or out of memory. */
477
+ pbw_ctx *pbw_pool_acquire(pbw_pool *pool);
478
+ void pbw_pool_release(pbw_pool *pool, pbw_ctx *ctx);
479
+ /* Idle contexts held now (for sizing/debugging, the printf side). */
480
+ size_t pbw_pool_idle(const pbw_pool *pool);
481
+ /* Bytes currently held in the context (for sizing/debugging). */
482
+ size_t pbw_ctx_used(const pbw_ctx *ctx);
483
+
484
+ /* Decode into the context instead of one allocation per value. A sealed
485
+ * context (one holding a previous decode) resets implicitly on entry, so a
486
+ * decode loop needs no reset call; earlier trees die with that reset. A
487
+ * failed decode resets too, so its partial trees never accumulate. */
488
+ pbw_status pbw_decode_ctx(pbw_ctx *ctx, const pbw_descriptor *desc,
489
+ const void *buf, size_t len, pbw_message **out);
490
+ /* Encode into the context's buffer. *out stays valid until the next
491
+ * pbw_encode_ctx()/pbw_ctx_reset()/pbw_ctx_free() on the same context. */
492
+ pbw_status pbw_encode_ctx(pbw_ctx *ctx, const pbw_message *msg,
493
+ const uint8_t **out, size_t *len);
494
+
495
+ /* Bounds for untrusted input. Zero fields mean the defaults: no byte cap and
496
+ * PBW_MAX_DEPTH nesting. A max_depth above PBW_MAX_DEPTH is clamped to it. */
497
+ typedef struct pbw_limits {
498
+ size_t max_bytes; /* reject inputs larger than this */
499
+ uint32_t max_depth; /* nesting cap, 0 = PBW_MAX_DEPTH */
500
+ } pbw_limits;
501
+
502
+ /* ------------------------------------------------------------------ wire */
503
+
504
+ /* The text and JSON mappings define '.' as the decimal separator, but strtod
505
+ * and snprintf follow LC_NUMERIC, which the embedding host may have set to a
506
+ * comma-decimal locale. The printers and parsers therefore translate the
507
+ * locale's separator when it is not '.', so the output stays valid under both.
508
+ * That check reads localeconv(), which the C standard does not make safe
509
+ * against a concurrent setlocale(): set the locale once at startup, before
510
+ * another thread calls into this library. */
511
+
512
+ /* Print msg in protobuf text format. *out is malloc'd, NUL-terminated and owned
513
+ * by the caller (pbw_free); *len excludes the NUL. Unknown fields are shown
514
+ * as numeric `field: value` lines, like the reference printer; those lines
515
+ * do not parse back (pass 0 for print_unknown_fields for round trips). */
516
+ pbw_status pbw_text_print(const pbw_message *msg, char **out, size_t *len);
517
+ /* Same, with explicit control over unknown fields (the conformance suite asks
518
+ * for both). */
519
+ pbw_status pbw_text_print_opts(const pbw_message *msg, int print_unknown_fields,
520
+ char **out, size_t *len);
521
+ /* Parse text format into a new message tree. Reserved field names are skipped
522
+ * silently; anything else unknown fails. A missing proto2 `required` field
523
+ * fails with PBW_ERR_REQUIRED, like the binary decoder. */
524
+ pbw_status pbw_text_parse(const pbw_descriptor *desc, const char *text,
525
+ size_t len, pbw_message **out);
526
+ /* Same with explicit bounds. Like the binary decoder, a max_depth above
527
+ * PBW_MAX_DEPTH clamps to it and a max_bytes of 0 means no byte cap; both are
528
+ * checked before any recursion, so a host on a small thread stack can lower the
529
+ * nesting cap instead of trusting PBW_MAX_DEPTH. */
530
+ pbw_status pbw_text_parse_limits(const pbw_descriptor *desc, const char *text,
531
+ size_t len, const pbw_limits *limits,
532
+ pbw_message **out);
533
+
534
+ /* Print msg in protobuf JSON mapping. *out is malloc'd, NUL-terminated and
535
+ * owned by the caller (pbw_free); *len excludes the NUL. Matches the
536
+ * reference printer semantically: 64-bit integers print quoted, bytes print
537
+ * as standard base64, enums print by name, well-known types use their JSON
538
+ * form (`Any`, `Timestamp`, `Duration`, `Struct`, `FieldMask`, wrappers).
539
+ * Unknown fields are not printed. A message that cannot be represented
540
+ * (invalid UTF-8, non-finite `Value`, out-of-range time) fails. */
541
+ pbw_status pbw_json_print(const pbw_message *msg, char **out, size_t *len);
542
+ /* Parse JSON mapping into a new message tree. Unknown fields fail unless
543
+ * `ignore_unknown_fields` is set (the conformance JSON_IGNORE_UNKNOWN
544
+ * category). A missing proto2 `required` field fails with PBW_ERR_REQUIRED.
545
+ * The well-known types are recognized by full message name and then require
546
+ * their real shape (`Any` 1=string `type_url`, 2=bytes `value`; Timestamp
547
+ * and Duration 1=int64 `seconds`, 2=int32 `nanos`); a schema that carries
548
+ * only the name is PBW_ERR_INVALID rather than a crash. */
549
+ typedef struct pbw_json_parse_options {
550
+ /* Skip unknown field names instead of failing. An `Any` whose `@type`
551
+ * does not resolve stays an error either way, like the reference parser. */
552
+ int ignore_unknown_fields;
553
+ } pbw_json_parse_options;
554
+ pbw_status pbw_json_parse_opts(const pbw_descriptor *desc, const char *text,
555
+ size_t len,
556
+ const pbw_json_parse_options *options,
557
+ pbw_message **out);
558
+ /* Same with default options (unknown fields fail). */
559
+ pbw_status pbw_json_parse(const pbw_descriptor *desc, const char *text,
560
+ size_t len, pbw_message **out);
561
+ /* Same with explicit bounds and options (either pointer may be NULL for the
562
+ * defaults). The nesting and byte caps behave like pbw_text_parse_limits();
563
+ * note that an array costs a level too, so a repeated message chain spends two
564
+ * levels per message (the default cap then rejects at 128, not 256). */
565
+ pbw_status pbw_json_parse_limits(const pbw_descriptor *desc, const char *text,
566
+ size_t len, const pbw_limits *limits,
567
+ const pbw_json_parse_options *options,
568
+ pbw_message **out);
569
+
570
+ /* Encode msg; *out is replaced with a malloc'd buffer owned by the caller
571
+ * (pbw_free). *out and *len are 0 on failure. */
572
+ pbw_status pbw_encode(const pbw_message *msg, uint8_t **out, size_t *len);
573
+ /* Encode into caller memory of `cap` bytes, so a binding can write straight
574
+ * into its own buffer. No allocation happens and nothing is freed; `cap` is
575
+ * the hard limit and the writer over-reserves up to 10 bytes per write, so
576
+ * `pbw_message_encoded_size(msg) + PBW_ENCODE_SLACK` may be needed even when
577
+ * the exact size is known. *len is the bytes written, 0 after any failure.
578
+ * PBW_ERR_LIMIT when the message does not fit. */
579
+ pbw_status pbw_encode_to(const pbw_message *msg, void *out, size_t cap,
580
+ size_t *len);
581
+ /* Decode buf into a new message of the given type. Unknown fields are kept.
582
+ *
583
+ * The returned tree is one allocation: pbw_message_free() on the root releases
584
+ * every submessage, repeated item and string in it, so values and submessages
585
+ * obtained from it must not be freed with pbw_value_free()/pbw_message_free()
586
+ * (those become no-ops on them). The tree is mutable: pbw_message_set()/
587
+ * clear()/set_message() work on it and their payloads are released normally. */
588
+ pbw_status pbw_decode(const pbw_descriptor *desc, const void *buf, size_t len,
589
+ pbw_message **out);
590
+
591
+ /* ------------------------------------------------------------------ limits */
592
+
593
+ /* Nesting cap the decoder enforces (100 in the reference implementations; 256
594
+ * here for the Erlang binding's 200-deep round-trips, which still rejects
595
+ * conformance test 20000). A decoder that walks wire bytes itself must use the
596
+ * same bound. The cap bounds recursion, not stack: one nesting level costs
597
+ * about 1.4 KB of C stack in a release build and up to 3.8 KB in a debug
598
+ * build (~1 MB under ASan/UBSan), so a thread that parses input up to the cap
599
+ * needs roughly 1 MB free (test_threads pins it to 2 MB; macOS worker threads
600
+ * default to 512 KB). Callers that cannot promise that stack use
601
+ * pbw_limits.max_depth to lower the cap for the binary decoder. */
602
+ #define PBW_MAX_DEPTH 256
603
+
604
+ /* Decode with explicit bounds; identical to pbw_decode() with NULL limits. */
605
+ pbw_status pbw_decode_limits(const pbw_descriptor *desc, const void *buf,
606
+ size_t len, const pbw_limits *limits,
607
+ pbw_message **out);
608
+ pbw_status pbw_decode_ctx_limits(pbw_ctx *ctx, const pbw_descriptor *desc,
609
+ const void *buf, size_t len,
610
+ const pbw_limits *limits, pbw_message **out);
611
+ /* Bounded descriptor load: like pbw_descriptor_set_load(), but rejects
612
+ * inputs larger than limits->max_bytes with PBW_ERR_LIMIT and caps message
613
+ * nesting at limits->max_depth (0 = PBW_MAX_DEPTH, above clamps to it).
614
+ * Descriptors stay trusted input; the bounds only cap resource use from
615
+ * oversized or hostile sets. NULL limits behaves exactly like
616
+ * pbw_descriptor_set_load(). */
617
+ pbw_status pbw_descriptor_set_load_limits(const void *data, size_t len,
618
+ const pbw_limits *limits,
619
+ pbw_schema **out);
620
+
621
+ /* Encode with map entries sorted by key, so equal messages encode to equal
622
+ * bytes regardless of insertion order. Non-map fields encode exactly as
623
+ * pbw_encode() writes them. */
624
+ pbw_status pbw_encode_deterministic(const pbw_message *msg, uint8_t **out,
625
+ size_t *len);
626
+ /* The caller-buffer twin of pbw_encode_deterministic(), with the same
627
+ * contract as pbw_encode_to(): no allocation, `cap` is the hard limit,
628
+ * PBW_ERR_LIMIT when the message does not fit. */
629
+ pbw_status pbw_encode_deterministic_to(const pbw_message *msg, void *out,
630
+ size_t cap, size_t *len);
631
+
632
+ /* ------------------------------------------------------------ visit scan */
633
+
634
+ /* One scanned field: raw wire content, no allocation, no value tree. */
635
+ typedef struct pbw_visit_value {
636
+ /* VARINT/32BIT/64BIT: raw wire bits (varints unfolded: no zigzag or sign
637
+ * extension applied). Unused for the length-delimited shapes below. */
638
+ uint64_t u64;
639
+ /* LEN: the payload bytes (a nested message, a packed run, a string); for
640
+ * START_GROUP the whole field (tag through the matching END_GROUP).
641
+ * Points into buf; NULL for the scalar shapes above. */
642
+ const uint8_t *data;
643
+ /* Payload/raw length; 0 for the scalar shapes. */
644
+ size_t len;
645
+ } pbw_visit_value;
646
+
647
+ /* Scan callback: field is NULL when the number is unknown to the schema.
648
+ * number/wire_type are what the wire carries: a known field may carry another
649
+ * wire type (a packed LEN for a repeated scalar, or a mismatch the reference
650
+ * decoders would keep as an unknown field). LEN data points into buf. Return
651
+ * PBW_OK to continue, anything else aborts the scan with that status. */
652
+ typedef pbw_status (*pbw_visit_fn)(void *ud, const pbw_field *field,
653
+ uint32_t number, uint32_t wire_type,
654
+ const pbw_visit_value *value);
655
+
656
+ /* Single-level scan of buf without building a message tree: one validating tag
657
+ * pass, one callback per field, no allocation. Nested messages and packed runs
658
+ * arrive as LEN payloads for the caller to recurse into (field->sub plus
659
+ * another pbw_visit); groups arrive as raw bytes. No required/enum checks:
660
+ * values are raw wire bits. fail_off (nullable) is always written: len on
661
+ * success, the failing/aborting field's byte offset otherwise. */
662
+ pbw_status pbw_visit(const pbw_descriptor *desc, const void *buf, size_t len,
663
+ pbw_visit_fn cb, void *ud, size_t *fail_off);
664
+ /* Same with explicit bounds; identical to pbw_visit() with NULL limits. Only
665
+ * max_bytes and the group-nesting cap apply: the scan itself never recurses. */
666
+ pbw_status pbw_visit_limits(const pbw_descriptor *desc, const void *buf,
667
+ size_t len, const pbw_limits *limits,
668
+ pbw_visit_fn cb, void *ud, size_t *fail_off);
669
+
670
+ /* --------------------------------------------------------------- streaming */
671
+
672
+ /* Sink for streaming encodes: return PBW_OK to continue, anything else aborts
673
+ * the encode with that status. */
674
+ typedef pbw_status (*pbw_sink_fn)(const uint8_t *data, size_t len,
675
+ void *opaque);
676
+
677
+ /* Encode msg and hand the bytes to sink, in 8 KiB chunks. */
678
+ pbw_status pbw_encode_sink(const pbw_message *msg, pbw_sink_fn sink,
679
+ void *opaque);
680
+ /* Length-delimited framing (varint length + message), the standard framing
681
+ * for a stream of messages. */
682
+ pbw_status pbw_encode_delimited(const pbw_message *msg, uint8_t **out,
683
+ size_t *len);
684
+ /* Same framing into caller memory: no allocation, `cap` is the hard limit.
685
+ * The writer over-reserves like pbw_encode_to(), so the guaranteed-fit cap is
686
+ * pbw_message_encoded_size(msg) + its length prefix + PBW_ENCODE_SLACK (the
687
+ * prefix is one byte under 128 bytes, one more per 7 bits above). *len is the
688
+ * whole frame, 0 after any failure. */
689
+ pbw_status pbw_encode_delimited_to(const pbw_message *msg, void *out,
690
+ size_t cap, size_t *len);
691
+
692
+ typedef struct pbw_istream pbw_istream;
693
+
694
+ /* Incremental delimited-message reader: feed() appends wire bytes as they
695
+ * arrive, next() decodes one message per call. next() writes NULL to *out
696
+ * and returns PBW_OK when the buffer holds no complete message yet. */
697
+ pbw_istream *pbw_istream_new(const pbw_limits *limits); /* NULL = defaults */
698
+ void pbw_istream_free(pbw_istream *s);
699
+ /* Drop buffered bytes (complete and partial frames alike). */
700
+ void pbw_istream_reset(pbw_istream *s);
701
+ pbw_status pbw_istream_feed(pbw_istream *s, const void *data, size_t len);
702
+ pbw_status pbw_istream_next(pbw_istream *s, const pbw_descriptor *desc,
703
+ pbw_message **out);
704
+ /* Decode one length-delimited frame (varint length + message) from buf: the
705
+ * one-shot twin of pbw_encode_delimited(). *consumed is the prefix + frame
706
+ * bytes, so a caller holding concatenated frames advances by it and decodes
707
+ * again. Trailing bytes are left for the caller; a truncated frame fails
708
+ * with PBW_ERR_INVALID (there is no "need more data" one-shot: use
709
+ * pbw_istream for that). */
710
+ pbw_status pbw_decode_delimited(const pbw_descriptor *desc, const void *buf,
711
+ size_t len, pbw_message **out,
712
+ size_t *consumed);
713
+ /* Same with explicit bounds; identical to pbw_decode_delimited() with NULL
714
+ * limits. */
715
+ pbw_status pbw_decode_delimited_limits(const pbw_descriptor *desc,
716
+ const void *buf, size_t len,
717
+ const pbw_limits *limits,
718
+ pbw_message **out, size_t *consumed);
719
+ /* The pbw_ctx twin: the tree lands in the context's arena (read-only, like
720
+ * pbw_decode_ctx_limits()) instead of one malloc block, so a framed stream
721
+ * decoded in a loop stops allocating. It resets a sealed context implicitly,
722
+ * exactly like pbw_decode_ctx(), so a frame loop needs no reset call. A
723
+ * declared frame length past limits->max_bytes is PBW_ERR_LIMIT before the body is decoded. */
724
+ pbw_status pbw_decode_delimited_ctx_limits(pbw_ctx *ctx,
725
+ const pbw_descriptor *desc,
726
+ const void *buf, size_t len,
727
+ const pbw_limits *limits,
728
+ pbw_message **out,
729
+ size_t *consumed);
730
+ /* Same with default bounds; identical to pbw_decode_delimited_ctx_limits()
731
+ * with NULL limits. */
732
+ pbw_status pbw_decode_delimited_ctx(pbw_ctx *ctx, const pbw_descriptor *desc,
733
+ const void *buf, size_t len,
734
+ pbw_message **out, size_t *consumed);
735
+ void pbw_free(void *ptr);
736
+ const char *pbw_strerror(pbw_status status);
737
+
738
+ #ifdef __cplusplus
739
+ }
740
+ #endif
741
+
742
+ #if defined(__GNUC__) || defined(__clang__)
743
+ #pragma GCC visibility pop
744
+ #endif
745
+
746
+ #endif /* PBWIRE_H */