Zephyr OS MQTT Publish Events: Read the Payload Before Treating the Message as Complete

An MQTT publish callback in Zephyr OS announces a payload that the application still needs to read. It does not hand over an owned, complete byte array simply because the event structure contains a payload member. Build message acceptance around the announced length and the payload-read results rather than dereferencing that member as received content.

This article examines Zephyr v4.4.0 client APIs and the payload-read implementation. The examples describe proposed software behavior. They do not claim an executed broker test, guaranteed delivery or a particular maximum safe message size.

Start with the event contract

The tagged MQTT header explicitly says that a publish event provides the payload size while its payload data parameter must be ignored. The application reads the content through the payload APIs. The ordinary helper is nonblocking and reports a byte count or a negative error; the read-all helper has a different success convention, returning zero after obtaining the requested count.

Keep that distinction visible in any wrapper. A zero from the read-all function is success; a byte count from the ordinary helper describes progress. Reusing one generic success test across both interfaces can make a correct transfer appear empty or can prematurely accept an incomplete message.

The event handler's ownership design should also state where the received content will live. A temporary scratch buffer suitable for parsing inside the handler is not automatically suitable for passing to a worker that runs after the buffer is reused.

Account for progress, not the requested chunk size

The v4.4.0 payload implementation caps a requested read to the remaining payload. After a positive transport result it reduces the remaining count by the actual bytes returned. A nonblocking minus EAGAIN leaves the payload outstanding. An empty remaining payload returns zero, whereas transport closure while bytes are still expected becomes a connection failure.

A hypothetical message of 150 bytes might be processed with a 64-byte scratch buffer. The request size is a capacity limit, not a guarantee that every call returns 64 bytes. Advance the destination or parser only by the positive count actually returned. Track the outstanding message length and stop accepting data only when the required bytes have been consumed or the operation fails.

Do not busy-loop indefinitely on minus EAGAIN. Choose the documented helper and event-loop integration appropriate to the application, preserving the unfinished payload state and servicing the transport when progress is possible. If a blocking helper is selected, assess its effect on the client's owner thread and other deadlines before using it in production.

Make rejection a connection-state decision

An application can reject a message because its content is unsupported or cannot fit its processing policy. That does not make unread bytes disappear from the stream. Define whether the integration will consume and discard the remaining payload through the supported path or deliberately end the connection. Do not return to ordinary application processing while pretending the rejected message was completely received.

A streaming parser may reduce memory requirements, but it still needs a bounded state and a clear final acceptance point. Receiving a valid-looking prefix is insufficient when a later chunk can invalidate the command. Keep side effects after complete validation unless the protocol explicitly defines safe incremental operations.

Exercise the boundary between notification and content

A proposed test should split payload delivery into uneven chunks and introduce a temporary no-data result between chunks. Verify that the application neither repeats bytes nor skips the unread portion. Then close the transport before the announced length is satisfied and confirm that no complete-message notification reaches the application consumer.

Include an empty payload and the read-all helper's zero-success behavior as separate cases. The useful result is a precise handoff: message metadata announces what must be read, payload APIs establish actual progress, and the application receives a complete validated object only when its chosen acceptance conditions are met.