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
** 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
** 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
** 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

6
README.html
View File

@ -555,7 +555,7 @@ pre.rouge .gs {
<div class="details">
<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="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 id="toc" class="toc2">
<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">
<ul>
<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>
</ul>
</div>
@ -662,7 +662,7 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
</div>
<div id="footer">
<div id="footer-text">
Last updated 2024-07-09 16:54:13 -0400
Last updated 2024-07-10 00:21:48 -0400
</div>
</div>
</body>

15
consts.go
View File

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

const (
// IndentDefault is the [IndentChars] to use if not specified.
IndentDefault string = "\t"
// SeperatorDefault is the [SeperatorChars] to use if not specified.
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 (
indentR uint = iota
indentRG
@ -26,18 +29,18 @@ const (
const indentOrigRec uint = 2

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
)

const (
// 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 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 (
AsciiNUL uint8 = iota // 0x00
AsciiSOH // 0x01
@ -73,6 +76,7 @@ const (
AsciiUS // 0x1f
)

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

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

12
funcs_request.go
View File

@ -34,7 +34,7 @@ func (r *Request) MarshalBinary() (data []byte, err error) {
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 {
return
}
@ -307,14 +307,14 @@ func (r *Request) UnmarshalBinary(data []byte) (err error) {
}
r.Checksum = new(uint32)
*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))
if _, err = buf.Read(b); err != nil {
return
}
// But we don't need to do anything with it.
// But don't need to do anything with it.
} 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
}

@ -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.
if _, err = msgBuf.Read(make([]byte, len(hdrBODYSTART)+(PackedNumSize*2))); err != nil {
return
@ -375,7 +375,7 @@ func (r *Request) UnmarshalBinary(data []byte) (err error) {
for idx := 0; idx < rgCnt; idx++ {
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 {
return
}

2
funcs_requestrecord.go
View File

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

// And now we handle the FVPs themselves.
// And now handle the FVPs themselves.
b = make([]byte, size)
if _, err = buf.Read(b); err != nil {
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++ {
recBuf = new(bytes.Buffer)

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

10
funcs_response.go
View File

@ -90,7 +90,7 @@ func (r *Response) MarshalBinary() (data []byte, err error) {
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 {
return
}
@ -120,7 +120,7 @@ func (r *Response) MarshalBinary() (data []byte, err error) {
hasErr = true
}

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

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

// Checksum -- ALWAYS present for responses!
// Checksum; ALWAYS present for responses!
if _, _, err = r.GenChecksum(); err != nil {
return
}
@ -426,7 +426,7 @@ func (r *Response) UnmarshalBinary(data []byte) (err error) {
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.
if _, err = msgBuf.Read(make([]byte, len(hdrBODYSTART)+(PackedNumSize*2))); err != nil {
return
@ -439,7 +439,7 @@ func (r *Response) UnmarshalBinary(data []byte) (err error) {
for idx := 0; idx < rgCnt; idx++ {
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 {
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++ {
recBuf = new(bytes.Buffer)

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