Protocol header (Bytefield)

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

A custom binary protocol is where these diagrams earn their keep, because there is no RFC for the reader to check against.

#What this example shows

  • A magic number, which is how the format identifies itself.

  • Version and flags fields, sized deliberately.

  • A trailing checksum after a variable body.

#A worked example

Open it, edit it, or copy the source below.

Protocol header (Bytefield)

The source, which you can paste into a new diagram and edit:

(defattrs :magic {:fill "#e2e8f0"})
(defattrs :meta {:fill "#e6eeff"})
(defattrs :crc {:fill "#e6fffa"})

(draw-column-headers)

(draw-box "magic 0x43 0x41 0x50 0x44" {:span 4 :attrs :magic})
(draw-box "ver" {:span 1 :attrs :meta})
(draw-box "flags" {:span 1 :attrs :meta})
(draw-box "hdr len" {:span 2 :attrs :meta})
(draw-box "body length (bytes)" {:span 4 :attrs :meta})
(draw-box "created at (unix seconds, LE)" {:span 8 :attrs :meta})
(draw-box "message id" {:span 16})
(draw-gap "body (body length bytes)")
(draw-box "crc32" {:span 4 :attrs :crc})
(draw-bottom)

#Making it your own

  • Put the magic number first; it is how a parser rejects the wrong file quickly.

  • Name the endianness on the fields where it matters, as this one does.

  • Reserve fields explicitly rather than leaving gaps for later.

The offsets are computed, not drawn.