cloudflared-mirror/vendor/github.com/google/gopacket/CONTRIBUTING.md

Contributing To gopacket

So you've got some code and you'd like it to be part of gopacket... wonderful! We're happy to accept contributions, whether they're fixes to old protocols, new protocols entirely, or anything else you think would improve the gopacket library. This document is designed to help you to do just that.

The first section deals with the plumbing: how to actually get a change submitted.

The second section deals with coding style... Go is great in that it has a uniform style implemented by 'go fmt', but there's still some decisions we've made that go above and beyond, and if you follow them, they won't come up in your code review.

The third section deals with some of the implementation decisions we've made, which may help you to understand the current code and which we may ask you to conform to (or provide compelling reasons for ignoring).

Overall, we hope this document will help you to understand our system and write great code which fits in, and help us to turn around on your code review quickly so the code can make it into the master branch as quickly as possible.

How To Submit Code

We use github.com's Pull Request feature to receive code contributions from external contributors. See https://help.github.com/articles/creating-a-pull-request/ for details on how to create a request.

Also, there's a local script gc in the base directory of GoPacket that runs a local set of checks, which should give you relatively high confidence that your pull won't fail github pull checks.

go get github.com/google/gopacket
cd $GOROOT/src/pkg/github.com/google/gopacket
git checkout -b <mynewfeature>  # create a new branch to work from
... code code code ...
./gc  # Run this to do local commits, it performs a number of checks

To sum up:

• DO
  • Pull down the latest version.
  • Make a feature-specific branch.
  • Code using the style and methods discussed in the rest of this document.
  • Use the ./gc command to do local commits or check correctness.
  • Push your new feature branch up to github.com, as a pull request.
  • Handle comments and requests from reviewers, pushing new commits up to your feature branch as problems are addressed.
  • Put interesting comments and discussions into commit comments.
• DON'T
  • Push to someone else's branch without their permission.

Coding Style

• Go code must be run through go fmt, go vet, and golint
• Follow http://golang.org/doc/effective_go.html as much as possible.
  • In particular, http://golang.org/doc/effective_go.html#mixed-caps. Enums should be be CamelCase, with acronyms capitalized (TCPSourcePort, vs. TcpSourcePort or TCP_SOURCE_PORT).
• Bonus points for giving enum types a String() field.
• Any exported types or functions should have commentary (http://golang.org/doc/effective_go.html#commentary)

Coding Methods And Implementation Notes

Error Handling

Many times, you'll be decoding a protocol and run across something bad, a packet corruption or the like. How do you handle this? First off, ALWAYS report the error. You can do this either by returning the error from the decode() function (most common), or if you're up for it you can implement and add an ErrorLayer through the packet builder (the first method is a simple shortcut that does exactly this, then stops any future decoding).

Often, you'll already have decode some part of your protocol by the time you hit your error. Use your own discretion to determine whether the stuff you've already decoded should be returned to the caller or not:

func decodeMyProtocol(data []byte, p gopacket.PacketBuilder) error {
  prot := &MyProtocol{}
  if len(data) < 10 {
    // This error occurred before we did ANYTHING, so there's nothing in my
    // protocol that the caller could possibly want.  Just return the error.
    return fmt.Errorf("Length %d less than 10", len(data))
  }
  prot.ImportantField1 = data[:5]
  prot.ImportantField2 = data[5:10]
  // At this point, we've already got enough information in 'prot' to
  // warrant returning it to the caller, so we'll add it now.
  p.AddLayer(prot)
  if len(data) < 15 {
    // We encountered an error later in the packet, but the caller already
    // has the important info we've gleaned so far.
    return fmt.Errorf("Length %d less than 15", len(data))
  }
  prot.ImportantField3 = data[10:15]
  return nil  // We've already added the layer, we can just return success.
}

In general, our code follows the approach of returning the first error it encounters. In general, we don't trust any bytes after the first error we see.

What Is A Layer?

The definition of a layer is up to the discretion of the coder. It should be something important enough that it's actually useful to the caller (IE: every TLV value should probably NOT be a layer). However, it can be more granular than a single protocol... IPv6 and SCTP both implement many layers to handle the various parts of the protocol. Use your best judgement, and prepare to defend your decisions during code review. ;)

Performance

We strive to make gopacket as fast as possible while still providing lots of features. In general, this means:

• Focus performance tuning on common protocols (IP4/6, TCP, etc), and optimize others on an as-needed basis (tons of MPLS on your network? Time to optimize MPLS!)
• Use fast operations. See the toplevel benchmark_test for benchmarks of some of Go's underlying features and types.
• Test your performance changes! You should use the ./gc script's --benchmark flag to submit any performance-related changes. Use pcap/gopacket_benchmark to test your change against a PCAP file based on your traffic patterns.
• Don't be TOO hacky. Sometimes, removing an unused struct from a field causes a huge performance hit, due to the way that Go currently handles its segmented stack... don't be afraid to clean it up anyway. We'll trust the Go compiler to get good enough over time to handle this. Also, this type of compiler-specific optimization is very fragile; someone adding a field to an entirely different struct elsewhere in the codebase could reverse any gains you might achieve by aligning your allocations.
• Try to minimize memory allocations. If possible, use []byte to reference pieces of the input, instead of using string, which requires copying the bytes into a new memory allocation.
• Think hard about what should be evaluated lazily vs. not. In general, a layer's struct should almost exactly mirror the layer's frame. Anything that's more interesting should be a function. This may not always be possible, but it's a good rule of thumb.
• Don't fear micro-optimizations. With the above in mind, we welcome micro-optimizations that we think will have positive/neutral impacts on the majority of workloads. A prime example of this is pre-allocating certain structs within a larger one:

type MyProtocol struct {
  // Most packets have 1-4 of VeryCommon, so we preallocate it here.
  initialAllocation [4]uint32
  VeryCommon []uint32
}

func decodeMyProtocol(data []byte, p gopacket.PacketBuilder) error {
  prot := &MyProtocol{}
  prot.VeryCommon = proto.initialAllocation[:0]
  for len(data) > 4 {
    field := binary.BigEndian.Uint32(data[:4])
    data = data[4:]
    // Since we're using the underlying initialAllocation, we won't need to
    // allocate new memory for the following append unless we more than 16
    // bytes of data, which should be the uncommon case.
    prot.VeryCommon = append(prot.VeryCommon, field)
  }
  p.AddLayer(prot)
  if len(data) > 0 {
    return fmt.Errorf("MyProtocol packet has %d bytes left after decoding", len(data))
  }
  return nil
}

Slices And Data

If you're pulling a slice from the data you're decoding, don't copy it. Just use the slice itself.

type MyProtocol struct {
  A, B net.IP
}
func decodeMyProtocol(data []byte, p gopacket.PacketBuilder) error {
  p.AddLayer(&MyProtocol{
    A: data[:4],
    B: data[4:8],
  })
  return nil
}

The caller has already agreed, by using this library, that they won't modify the set of bytes they pass in to the decoder, or the library has already copied the set of bytes to a read-only location. See DecodeOptions.NoCopy for more information.

Enums/Types

If a protocol has an integer field (uint8, uint16, etc) with a couple of known values that mean something special, make it a type. This allows us to do really nice things like adding a String() function to them, so we can more easily display those to users. Check out layers/enums.go for one example, as well as layers/icmp.go for layer-specific enums.

When naming things, try for descriptiveness over suscinctness. For example, choose DNSResponseRecord over DNSRR.