Pepto Symbol

Pepto Symbol lets you use S3 as a Windows symbol server for debugging Windows-based applications.

Wait, what's a symbol server?

"Symbol files" (aka PDB files) contain information about your software that a debugger can use to show you backtraces, local variables, etc. They are generated by the compiler when you build your software. Debugging is a nightmare without symbols. Really.

A "symbol server" hosts symbol files for Windows-based software. Debuggers use symbol servers to obtain symbol files for the software you're debugging automatically. John Robbins has written a great article explaining all of this and more on his blog. Symbol servers can serve symbol files over HTTP or a Windows file share.

That doesn't sound so hard. Why do I need this?

symstore.exe, which creates the directory structure that the symbol server serves, and symsrv.dll, which implements the logic for retrieving symbols from a symbol server, operate case-insensitively (like much Windows software). This means that symsrv.dll might ask for symbols using a URL that uses uppercase where symstore.exe used lowercase, or vice versa.

Many web servers treat URLs case-insensitively. S3 does not. So one job of Pepto Symbol is to provide case-insensitive access to symbol files stored on S3.

In addition, if you try to access a file that doesn't exist on S3, you will get a 403 Forbidden error, rather than 404 Not Found. When symsrv.dll gets a 403 error from a symbol server, it blacklists that server for the rest of the debugging session. So Pepto Symbol also converts 403 errors to 404 errors.

Requirements

1. You must use all-lowercase keys when uploading your symbols to S3.
2. You need a server on which Pepto Symbol can run as an HTTP proxy.

Usage

Let's say you've uploaded your symbols (using lowercased keys, remember!) to http://my-bucket.s3.amazonaws.com/awesome/symbols, and that you're going to deploy Pepto Symbol to http://pepto-symbol.gadgetron.com/.

First, deploy Pepto Symbol to a server. Pepto Symbol comes preconfigured for deployment on Heroku:

heroku create --stack cedar
heroku config:add S3_BUCKET=my-bucket
git push heroku master

(It should be fairly simple to deploy it elsewhere if needed.)

Next, add the following URL to your symbol path:

http://pepto-symbol.gadgetron.com/awesome/symbols

That's it!

Path Prefix

You can add an optional PATH_PREFIX environment variables for shorter URLs. This prefix will be prepended to all requests paths to the S3 bucket.

heroku config:add PATH_PREFIX=/awesome/symbols

Now the symbol server URL can be http://pepto-symbol.gadgetron.com.

Configuration

The server is a small Rust binary configured through environment variables:

Variable	Default	Meaning
TARGET_HOST	(required)	Upstream host (and optional port) that symbols are fetched from over HTTPS.
PATH_PREFIX	empty	Prepended to every upstream path.
PORT	8080	Port to listen on.
UPSTREAM_TIMEOUT_MS	10000	Abandon an upstream fetch that makes no progress for this long (504 before headers; aborted connection mid-body). 0 disables it.
UPSTREAM_POOL_MAX_IDLE	256	Idle keep-alive connections kept open to the upstream for reuse. 0 opens a new connection per fetch.
EXTRA_CA_CERTS	unset	PEM file of extra CA certificates to trust for the upstream (used by the tests).
TOKIO_WORKER_THREADS	CPU count	Worker threads for the async runtime.

Running locally

TARGET_HOST=artifacts.electronjs.org PATH_PREFIX=/symbols cargo run --release

Run the checks CI runs with:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

Deploying to Heroku

Production uses the emk/rust buildpack, which reads RustConfig and runs the binary named in Procfile. Keep VERSION in RustConfig in sync with rust-toolchain.toml.

Source

Pepto Symbol's Git repository is available on GitHub, and can be browsed at https://github.com/aroben/pepto-symbol. You can clone the repository with this command:

git clone https://github.com/aroben/pepto-symbol

Contributing

If you'd like to hack on Pepto Symbol, follow these instructions:

1. Fork the project to your own account
2. Clone down your fork
3. Create a thoughtfully named topic branch to contain your change
4. Hack away
5. If you are adding new functionality, document it in README.md
6. Do not change the version number, I will do that on my end
7. If necessary, rebase your commits into logical chunks, without errors
8. Push the branch up to GitHub
9. Send a pull request for your branch

Copyright

Copyright (c) 2012 Adam Roben. See the LICENSE file for details.