Add initial implementation of Postcard-C by sphw · Pull Request #220 · jamesmunns/postcard

sphw · 2025-04-06T22:28:28Z

This PR adds a single header file implementation of the postcard spec in C. It's designed to be a relatively low-level API that allows users to manually write serialization and deserialization logic. It uses a BYOB (bring your own buffer) design, where the user has to pass a pre-allocated buffer of data. As such, it does not do any memory management on its own.

You can find more details on usage in README.md and example.c

I've tested this implementation as part of a C++ code generation system, and it works well on the types I've thrown at it. That being said, I can't guarantee that it is bug-free, and I would like to add a test suite that tests this implementation against the Rust implementation.

I will also be open-sourcing a C++ code generator that uses postcard-schema and postcard-c to generate high-level C++ structs.

netlify · 2025-04-06T22:28:52Z

✅ Deploy Preview for cute-starship-2d9c9b canceled.

Name	Link
🔨 Latest commit	`a733d69`
🔍 Latest deploy log	https://app.netlify.com/sites/cute-starship-2d9c9b/deploys/67f30c3ad6f7b1000811f89c

i509VCB

I also noticed that encoding u128 and i128 is not currently possible. Although I do understand that 128-bit types are special and require checking the compiler with proprocessor code.

i509VCB · 2025-04-12T06:07:47Z

source/postcard-c/postcard.h

+postcard_error_t postcard_encode_byte_array(postcard_slice_t* slice,
+    const uint8_t* bytes,
+    size_t length);


Would it be helpful to have a way to determine if there is enough room in the slice to push the array, without actually writing anything? (And other functions like this)

This is a potential problem across all of the functions, not just byte array. The trouble is that it would make encoding essentially a two-step operation: one to check how much size a varint takes, and another to actually encode it.

In the use cases I envisioned for this, I don't think this will cause practical problems. The first is a higher-level code generator that will pre-allocate memory based on the calculated encoded size. Another is serializing messages to fixed-size buffers. In that case, I'm not too concerned if there is half-written data, as long as the functions properly error out.

I think we can recommend that users run the postcard_size functions themselves if they never want to write data when the buffer isn't big enough.

a bit tangential to the discussion, but relevant for this (and similar APIs):
rather than passing a pointer you could pass an array - there's a fancy C notation (since C99) which allows you to specify the parameter which gives the length and the compiler will validate it. but the length parameter has to come before the array, otherwise it doesn't work (until this proposal gets standardised).

this works:

int foo(unsigned int len, char foo[static len]);

i509VCB · 2025-04-12T06:11:20Z

source/postcard-c/example.c

@@ -0,0 +1,121 @@
+#include "postcard.h"


There should probably be an SPDX header here. I do plan to use Postcard-C in projects where this is required.

Yeah that makes sense. I can add a SPDX header for MIT + Apache dual license to match the rest of the repo

i509VCB · 2025-04-12T06:18:08Z

source/postcard-c/postcard.h

+typedef enum {
+    POSTCARD_SUCCESS = 0,
+    POSTCARD_ERROR_BUFFER_TOO_SMALL,
+    POSTCARD_ERROR_INVALID_INPUT,
+    POSTCARD_ERROR_INCOMPLETE_DATA,
+    POSTCARD_ERROR_OVERFLOW
+} postcard_error_t;


I would prefer each error code to get an explicitly defined value. Whether the error values are positive or negative values is a different question.

i509VCB · 2025-04-12T06:19:13Z

source/postcard-c/postcard.h

+/// - string - a pointer to the string to encode. This string should be utf8
+/// encoded string. It shouldn't be null-terminated.


Is should a strong enough guarantee here? Or should it be considered undefined behavior if the string is NOT valid UTF-8?

i509VCB · 2025-04-12T06:19:27Z

source/postcard-c/postcard.h

+/// - slice - a pointer to an initialized `postcard_slice_t`
+/// - string - a pointer to the string to encode. This string should be utf8
+/// encoded string. It shouldn't be null-terminated.
+/// - length - the length of the string


To make it more clear that this is talking about each byte to be written and not the number of codepoints.

Suggested change

/// - length - the length of the string

/// - length - the length of the string in bytes

i509VCB · 2025-04-12T06:24:14Z

source/postcard-c/postcard.h

@@ -0,0 +1,1184 @@
+#ifndef POSTCARD_H


Top of header documentation should probably include a link to the specification.

i509VCB · 2025-04-12T06:27:42Z

source/postcard-c/postcard.h

+        return POSTCARD_ERROR_BUFFER_TOO_SMALL;
+
+    uint32_t bits;
+    memcpy(&bits, &value, sizeof(bits));


Should we use the memcpy in the standard library or make the caller pick the memcpy?

One pattern I often see is that a library has a seperate memcpy function, like a postcard_memcpy. This would let the caller define it's own memcpy implementation.

I've been going back and forth on what the best behavior is here. Personally I like to use a minimal libc (i.e newlib) on embedded devices, but I can understand not wanting to rely on that. I think the ergonomic benefits for non-embedded development are important though.

A good way to do it might be to use __has_include to check if string is available and use that version of memcpy if it exists. Alternatively we could use a preprocessor definition to allow the user to optionally override the memcpy impl

rursprung · 2025-06-19T10:43:30Z

source/postcard-c/postcard.h

+} postcard_slice_t;
+
+/// postcard_c error codes
+typedef enum {


i know that this is currently pure C, but doesn't pulling it into a C++ code base pollute the namespace (unless you #include it within a namespace)?
would it make sense to make the header C & C++ and use #ifdef __cplusplus copiously to decide between the two? that'd e.g. allow using enum class rather than typedef enum

add initial impl of postcard-c

e1266a8

fix: cast value to uint64_t to avoid UB

a733d69

i509VCB reviewed Apr 12, 2025

View reviewed changes

rursprung reviewed Jun 19, 2025

View reviewed changes

jamesmunns mentioned this pull request Jun 19, 2025

Tracking Issue: Postcard Q2 '25 Triage #241

Open

		/// - string - a pointer to the string to encode. This string should be utf8
		/// encoded string. It shouldn't be null-terminated.

	/// - length - the length of the string
	/// - length - the length of the string in bytes

Conversation

sphw commented Apr 6, 2025

Uh oh!

netlify bot commented Apr 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cute-starship-2d9c9b canceled.

Uh oh!

i509VCB left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

i509VCB Apr 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented Apr 6, 2025 •

edited

Loading

i509VCB Apr 12, 2025 •

edited

Loading