434 GitHub stars and counting — protocolbuffers/protoscope is a Go project TopGit is tracking across repositories on the platform. Protoscope is a simple, human-editable language for representing and emitting the Protobuf wire format.
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
Protoscope is a simple, human-editable language for representing and emitting
the
Protobuf wire format.
It is inspired by, and is significantly based on,
DER ASCII, a similar tool for working
with DER and BER, wire formats of ASN.1.
Unlike most Protobuf tools, it is normally ignorant of schemata specified in
.proto files; it has just enough knowledge of the wire format to provide
primitives for constructing messages (such as field tags, varints, and length
prefixes). A disassembler is included that uses heuristics to try convert
encoded Protobuf into Protoscope, although the heuristics are necessarily
imperfect.
We provide the Go package github.com/protocolbuffers/protoscope, as well as
the protoscope tool, which can be installed with the Go tool via
go install github.com/protocolbuffers/protoscope/cmd/protoscope...@latest
go install will place the binary in the GOBIN directory, which is ~/go/bin
by default. See the
docs for go install
for more details.
For the language specification and basic examples, see
language.txt. Example disassembly can be found under
./testdata.
Cookbook
Protoscope can be used in a number of different ways to inspect or create binary
Protobuf data. This isn't the full breadth of usecases, but they are the ones
Protoscope (and its ancestor, DER ASCII) were designed for.
Exploring Binary Dumps
Sometimes, while working on a library that emits wire format, it may be
necessary to debug the precise output of a test failure. If your test prints out
a hex string, you can use the xxd command to turn it into raw binary data and
pipe it into protoscope.
Consider the following example of a message with a google.protobuf.Any field:
Modifying the embedded string with a hex editor is very painful, because it's
possible that the length prefix needs to be updated, which can lead to the
length prefix on outer messages needing to be changed as well. This is made
worse by length prefixes being varints, which may grow or shrink and feed into
further outer length prefix updates.
But protoscope makes this into a simple disassemble, edit, assembly loop:
The -message-type option from above can be used when you know the schema to
make it easier to find specific fields.
Describing Invalid Binaries
Because Protoscope has a very weak understanding of Protobuf, it can be used to
create invalid encodings to verify that some invariant is actually checked by a
production parser.
For example, the following Protoscope text can be used to create a test that
ensures a too-long length prefix is rejected as invalid.
1: {
2:LEN 5 # Explicit length prefix.
"oops" # One byte too short.
}
This is more conveinent than typing out bytes by hand, because Protoscope takes
care of tedious details like length prefixes, varint encoding, float encoding,
and other things not relevant to the test. It also permits comments, which can
be used to specify why the Protoscope snippet produces a broken binary.
Protoscope itself generates test data using Protoscope, which is then checked
in. Other projects can either check in binary data directly, or use the build
system to invoke protoscope, such as with a Bazel genrule().
Backwards Compatibility
The Protoscope language itself may be extended over time, but the intention is
for extensions to be backwards-compatible. Specifically:
The command-line interface to protoscope will remain compatible, though
new options may be added in the future.
Previously valid Protoscope will remain valid and produce the same output.
In particular, checking in test data as Protoscope text should be
future-proof.
Previously invalid Protoscope may become valid in the future if the language
is extended.
Disassembly is necessarily a heuristic, so its output may change over
time, but it is guaranteed to produce Protoscope output that will reassemble
to the original byte string. protoscope | protoscope -s is always
equivalent to cat.
TopGit's last sync did not record any GitHub topics for protocolbuffers/protoscope. GitHub topics appear in the right sidebar of a repository page; that's the authoritative place to check.
How active is development on protocolbuffers/protoscope?
The most recent commit recorded on protocolbuffers/protoscope was 2.7 years ago, based on the GitHub push timestamp. The repository has 56 forks — one of the better signals of community interest.
How many stars does protocolbuffers/protoscope have?
protocolbuffers/protoscope has 434 GitHub stars — refresh the page for the live number, or check github.com/protocolbuffers/protoscope. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
What is protocolbuffers/protoscope?
protocolbuffers/protoscope (protocolbuffers/protoscope) is a Go project on GitHub. From the project's own README: Protoscope is a simple, human-editable language for representing and emitting the Protobuf wire format.
What language is protocolbuffers/protoscope written in?
protocolbuffers/protoscope is written primarily in Go. GitHub's language field is based on the largest share of bytes in the default branch.
Read full README in the tab above.
Want a second opinion on protoscope?
Ask an AI that can read this page — one click and you get its take on protoscope.