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.
- checksums.yaml +4 -4
- data/ext/pbwire_ext/core_arena.c +322 -0
- data/ext/pbwire_ext/core_ctx.c +334 -0
- data/ext/pbwire_ext/core_decode.c +1735 -0
- data/ext/pbwire_ext/core_descriptor_set.c +1482 -0
- data/ext/pbwire_ext/core_encode.c +1606 -0
- data/ext/pbwire_ext/core_json.c +4792 -0
- data/ext/pbwire_ext/core_message.c +1100 -0
- data/ext/pbwire_ext/core_schema.c +1459 -0
- data/ext/pbwire_ext/core_stream.c +450 -0
- data/ext/pbwire_ext/core_text.c +2583 -0
- data/ext/pbwire_ext/core_wire.c +735 -0
- data/ext/pbwire_ext/core_wkt.c +255 -0
- data/ext/pbwire_ext/extconf.rb +8 -7
- data/ext/pbwire_ext/internal.h +980 -0
- data/ext/pbwire_ext/pbwire.h +746 -0
- metadata +15 -15
- data/.diffend-unextracted-0 +0 -34
|
@@ -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 */
|