r00t2/go_wireproto
1
0
Fork 0
Code Issues Pull Requests Activity

v1.0.1

Browse Source 
FIX:
* Cleaned up some documentation
This commit is contained in:
brent saner 2024-07-10 00:40:12 -04:00
parent d4bb259b83
commit 9b39811206
Signed by: bts
GPG Key ID: 8C004C2F93481F6B
8 changed files with 30 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.adoc
View File

@ -52,7 +52,7 @@ The following are a wishlist or things planned that may come in later versions.
* More clear errors * More clear errors
** Currently during e.g. `UnmarshalBinary` calls, just an `io.EOF` will be returned if the buffer is exhausted early. This may be able to be a little more context-helpful by using the `Err*` errors. ** Currently during e.g. `UnmarshalBinary` calls, just an `io.EOF` will be returned if the buffer is exhausted early. This may be able to be a little more context-helpful by using the `Err*` errors.
* Confirmation of read/write sizes in buffers * Confirmation of read/write sizes in buffers
** We know the sizes they *should* be, there's no reason to not confirm it. ** The sizes they *should* be are known, there's no reason to not confirm it.
* Goroutines * Goroutines
** This of course won't work for serializing and keeping *order* of children (e.g. RG => Record); that'd still need to be ordered, but it will allow for parallel parsing *of* those children. Should benchmark, though; it may not be worth it. ** This of course won't work for serializing and keeping *order* of children (e.g. RG => Record); that'd still need to be ordered, but it will allow for parallel parsing *of* those children. Should benchmark, though; it may not be worth it.
* `context.Context` support for `Read*` and `Write*` funcs * `context.Context` support for `Read*` and `Write*` funcs

6
README.html
View File

@ -555,7 +555,7 @@ pre.rouge .gs {
<div class="details"> <div class="details">
<span id="author" class="author">Brent Saner</span><br> <span id="author" class="author">Brent Saner</span><br>
<span id="email" class="email"><a href="mailto:bts@square-r00t.net">bts@square-r00t.net</a></span><br> <span id="email" class="email"><a href="mailto:bts@square-r00t.net">bts@square-r00t.net</a></span><br>
<span id="revdate">Last rendered 2024-07-10 00:18:53 -0400</span> <span id="revdate">Last rendered 2024-07-10 00:40:13 -0400</span>
</div> </div>
<div id="toc" class="toc2"> <div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div> <div id="toctitle">Table of Contents</div>
@ -630,7 +630,7 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
<div class="ulist"> <div class="ulist">
<ul> <ul>
<li> <li>
<p>We know the sizes they <strong>should</strong> be, there&#8217;s no reason to not confirm it.</p> <p>The sizes they <strong>should</strong> be are known, there&#8217;s no reason to not confirm it.</p>
</li> </li>
</ul> </ul>
</div> </div>
@ -662,7 +662,7 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
</div> </div>
<div id="footer"> <div id="footer">
<div id="footer-text"> <div id="footer-text">
Last updated 2024-07-09 16:54:13 -0400 Last updated 2024-07-10 00:21:48 -0400
</div> </div>
</div> </div>
</body> </body>

15
consts.go
View File

@ -12,11 +12,14 @@ var (
) )


const ( const (
// IndentDefault is the [IndentChars] to use if not specified.
IndentDefault string = "\t" IndentDefault string = "\t"
// SeperatorDefault is the [SeperatorChars] to use if not specified.
SeparatorDefault string = " " SeparatorDefault string = " "
maxByteLine int = 12 // split if a value is more than this number of bytes.. maxByteLine int = 12 // (Split a hex string in a Model if a value is more than this number of bytes.)
) )


// Default indent levels.
const ( const (
indentR uint = iota indentR uint = iota
indentRG indentRG
@ -26,18 +29,18 @@ const (
const indentOrigRec uint = 2 const indentOrigRec uint = 2


const ( const (
// ProtoVersion specifies the protocol version for the specification of a Message. // ProtoVersion specifies the protocol version for the specification of a [Message].
ProtoVersion uint32 = 1 ProtoVersion uint32 = 1
) )


const ( const (
// PackedNumSize is the size (length of bytes) of a packed unsigned integer. // PackedNumSize is the size (length of bytes) of a packed unsigned integer.
PackedNumSize int = 4 // They're all uint32's. PackedNumSize int = 4 // (They're all uint32's.)
// CksumPackedSize is the size (length of bytes) of the checksum algorithm used. // CksumPackedSize is the size (length of bytes) of the checksum algorithm used.
CksumPackedSize int = 4 // CRC32 is a big-endian uint32, but if we use a different algo we need to change this. CksumPackedSize int = 4 // CRC32 is represented by a big-endian uint32, but if a different algo is used, this will need to be changed.
) )


// See https://square-r00t.net/ascii.html for further details. // See https://square-r00t.net/ascii.html for further details on ASCII symbols.
const ( const (
AsciiNUL uint8 = iota // 0x00 AsciiNUL uint8 = iota // 0x00
AsciiSOH // 0x01 AsciiSOH // 0x01
@ -73,6 +76,7 @@ const (
AsciiUS // 0x1f AsciiUS // 0x1f
) )


// Response Status indicator bytes.
const ( const (
RespStatusByteOK uint8 = AsciiACK RespStatusByteOK uint8 = AsciiACK
RespStatusByteErr = AsciiNAK RespStatusByteErr = AsciiNAK
@ -95,5 +99,6 @@ var (
) )


const ( const (
// WriteChunkSize is the default size of chunking to use (in bytes) when using chunked Write* functions (i.e. non-segmented).
WriteChunkSize int = 1024 WriteChunkSize int = 1024
) )

12
funcs_request.go
View File

@ -34,7 +34,7 @@ func (r *Request) MarshalBinary() (data []byte, err error) {
msgSize += i.Size() msgSize += i.Size()
} }


// The message "body" - we do this first so we can checksum (if not nil). // The message "body" - this is done first so the body can be checksummed (if not nil).
if _, err = msgBuf.Write(hdrBODYSTART); err != nil { if _, err = msgBuf.Write(hdrBODYSTART); err != nil {
return return
} }
@ -307,14 +307,14 @@ func (r *Request) UnmarshalBinary(data []byte) (err error) {
} }
r.Checksum = new(uint32) r.Checksum = new(uint32)
*r.Checksum = byteOrder.Uint32(b) *r.Checksum = byteOrder.Uint32(b)
// Since we've only read the checksum, we now also have to read in the MSGSTART... // Since only the checksum has been read, now read the MSGSTART...
b = make([]byte, len(hdrMSGSTART)) b = make([]byte, len(hdrMSGSTART))
if _, err = buf.Read(b); err != nil { if _, err = buf.Read(b); err != nil {
return return
} }
// But we don't need to do anything with it. // But don't need to do anything with it.
} else { } else {
// We've already read MSGSTART as part of the checksum check. // MSGSTART has already been read as part of the checksum check.
r.Checksum = nil r.Checksum = nil
} }


@ -362,7 +362,7 @@ func (r *Request) UnmarshalBinary(data []byte) (err error) {
} }
} }


// Now that we've validated the checksum (if provided), we trim the msgBuf to only RGs. // Now that the checksum (if provided) has validated, trim the msgBuf to only RGs.
// Skip over the BODYSTART, record group count, and record group size. // Skip over the BODYSTART, record group count, and record group size.
if _, err = msgBuf.Read(make([]byte, len(hdrBODYSTART)+(PackedNumSize*2))); err != nil { if _, err = msgBuf.Read(make([]byte, len(hdrBODYSTART)+(PackedNumSize*2))); err != nil {
return return
@ -375,7 +375,7 @@ func (r *Request) UnmarshalBinary(data []byte) (err error) {
for idx := 0; idx < rgCnt; idx++ { for idx := 0; idx < rgCnt; idx++ {
rgBuf = new(bytes.Buffer) rgBuf = new(bytes.Buffer)


// The RG unmarshaler handles the record count, but we need to read it to discard it in msgBuf. // The RG unmarshaler handles the record count, but it needs to be put in msgBuf to do that.
if _, err = io.CopyN(rgBuf, msgBuf, int64(PackedNumSize)); err != nil { if _, err = io.CopyN(rgBuf, msgBuf, int64(PackedNumSize)); err != nil {
return return
} }

2
funcs_requestrecord.go
View File

@ -186,7 +186,7 @@ func (r *RequestRecord) UnmarshalBinary(data []byte) (err error) {
} }
size = UnpackInt(b) size = UnpackInt(b)


// And now we handle the FVPs themselves. // And now handle the FVPs themselves.
b = make([]byte, size) b = make([]byte, size)
if _, err = buf.Read(b); err != nil { if _, err = buf.Read(b); err != nil {
return return

4
funcs_requestrecordgroup.go
View File

@ -199,8 +199,8 @@ func (r *RequestRecordGroup) UnmarshalBinary(data []byte) (err error) {
for idx := 0; idx < cnt; idx++ { for idx := 0; idx < cnt; idx++ {
recBuf = new(bytes.Buffer) recBuf = new(bytes.Buffer)


// We skip over the KVP count; that's handled in the record Unmarshaler. // Skip over the KVP count; that's handled in the record Unmarshaler.
// We *do*, however, need to save it to the recBuf. // It does, however, need to be written to recBuf.
if _, err = io.CopyN(recBuf, buf, int64(PackedNumSize)); err != nil { if _, err = io.CopyN(recBuf, buf, int64(PackedNumSize)); err != nil {
return return
} }

10
funcs_response.go
View File

@ -90,7 +90,7 @@ func (r *Response) MarshalBinary() (data []byte, err error) {
msgSize += i.Size() msgSize += i.Size()
} }


// The message "body" - we do this first so we can checksum . // The message "body" - this is done first so it can be checksummed.
if _, err = msgBuf.Write(hdrBODYSTART); err != nil { if _, err = msgBuf.Write(hdrBODYSTART); err != nil {
return return
} }
@ -120,7 +120,7 @@ func (r *Response) MarshalBinary() (data []byte, err error) {
hasErr = true hasErr = true
} }


// Now we write the response as a whole. // Now write the response as a whole.


// Status // Status
if r.Status == RespStatusByteOK && hasErr { if r.Status == RespStatusByteOK && hasErr {
@ -130,7 +130,7 @@ func (r *Response) MarshalBinary() (data []byte, err error) {
return return
} }


// Checksum -- ALWAYS present for responses! // Checksum; ALWAYS present for responses!
if _, _, err = r.GenChecksum(); err != nil { if _, _, err = r.GenChecksum(); err != nil {
return return
} }
@ -426,7 +426,7 @@ func (r *Response) UnmarshalBinary(data []byte) (err error) {
return return
} }


// Now that we've validated the checksum, we trim the msgBuf to only RGs. // Now that the checksum has validated, trim the msgBuf to only RGs.
// Skip over the BODYSTART, record group count, and record group size. // Skip over the BODYSTART, record group count, and record group size.
if _, err = msgBuf.Read(make([]byte, len(hdrBODYSTART)+(PackedNumSize*2))); err != nil { if _, err = msgBuf.Read(make([]byte, len(hdrBODYSTART)+(PackedNumSize*2))); err != nil {
return return
@ -439,7 +439,7 @@ func (r *Response) UnmarshalBinary(data []byte) (err error) {
for idx := 0; idx < rgCnt; idx++ { for idx := 0; idx < rgCnt; idx++ {
rgBuf = new(bytes.Buffer) rgBuf = new(bytes.Buffer)


// The RG unmarshaler handles the record count, but we need to read it into msgBuf. // The RG unmarshaler handles the record count, but it needs to be in msgBuf to do that.
if _, err = io.CopyN(rgBuf, msgBuf, int64(PackedNumSize)); err != nil { if _, err = io.CopyN(rgBuf, msgBuf, int64(PackedNumSize)); err != nil {
return return
} }

4
funcs_responserecordgroup.go
View File

@ -189,8 +189,8 @@ func (r *ResponseRecordGroup) UnmarshalBinary(data []byte) (err error) {
for idx := 0; idx < cnt; idx++ { for idx := 0; idx < cnt; idx++ {
recBuf = new(bytes.Buffer) recBuf = new(bytes.Buffer)


// We skip over the KVP count; that's handled in the record Unmarshaler. // Skip over the KVP count; that's handled in the record Unmarshaler.
// We *do*, however, need to save it to the recBuf. // It does need to be written to recBuf, though.
if _, err = io.CopyN(recBuf, buf, int64(PackedNumSize)); err != nil { if _, err = io.CopyN(recBuf, buf, int64(PackedNumSize)); err != nil {
return return
} }