go_wireproto/README.adoc

Go WireProto API Documentation

Table of Contents

• 1. Reference
• 2. License
• 3. TODO

1. Reference

In addition to the documentation found in this document and the specification, library usage documentation can be found at the Golang module documentation page:

2. License

This library is licensed for use, inclusion, and distribution under the "3-Clause BSD" license.

Full License

Unresolved directive in <stdin> - include::LICENSE[]

3. TODO

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

  • 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

  • This is a relatively low priority as the passed net.Conn will likely return an error if its own context is canceled. This can be handled in the caller downstream.

• Better/more strict interfaces

• Maps for generic should have any, not interface{} values

• FVP should have its own method to a map[string][]byte return value

• "Getters and Setters" (ew, I know, but compromises are made with flexibility)

  • .Append*() methods to append any type to any parent type. e.g. <Response>.AppendFVP(<FieldValuePair>) would append an FVP to the most recent ResponseRecord to the most recent ResponseRecordGroup (or create if they don’t exist), <Response>.AppendRecord(…​) for appending a record to most recent record group etc.

  • .Get()/.Set() on a Response/Request to get/set a slice of values (<FieldValue>) from filter criteria as struct (e.g. field name, how many, first X, last X, etc.)

  • .GetPath*() and .SetPath*() to use [RG_N[R_N[FVP_N]]] indexing (e.g. 0, 0, 0 for RecordGroup 0/Record 0/FVP 0, 1, 3, 5 for RecordGroup 1/Record 3/FVP 5, etc.) multidimentional indexing

    • Allow specific lookups/sets by multidimentional array index to return FVP (.GetIndex(idx) where idx is a fixed-size array of dimensions for object’s children paths); e.g. <Response>.GetIndex(idx), idx is [3]int and returns FVP)

    • Allow lookups/sets by variable length index (.GetIndexDynamic(idx), where idx is a 1 to n-size slice of dimensions for object’s children paths (e.g. <Response>.GetIndexDynamic([]int{0, 0}) returns any(<Record>) but <Response>.GetIndexDynamic([]int{0, 0, 0}) returns any(FieldValuePair))

      • negative value indicates all children

    • Lookups/sets at fixed levels (e.g. <RecordGroup>.GetRecord(idx), idx is [1]int, but <RecordGroup>.GetFVP(idx), idx is [2]int) for type safety

    • All objects have .ID() that returns their index/"path"/"key" from the root, and .Index() that returns their index within their immediate parent

      • This obviously requires a .Resolve() first