Home

Awesome

Sandstorm Raw API Example App

This is an example Sandstorm application which uses the raw Cap'n Proto-based Sandstorm API to serve a web UI without an HTTP server. Most apps instead use sandstorm-http-bridge wrapping a traditional server, but this one does't.

Why do that?

You might want to write a Sandstorm app using the raw API if:

That said, you should prefer sandstorm-http-bridge around a traditional HTTP server if:

Instructions

  1. Get a Linux machine.
  2. Install Cap'n Proto. You'll need to use the latest code from git, not a release version, because Sandstorm and Cap'n Proto are developed together and Sandstorm uses unreleased features from Cap'n Proto.
  3. Install Sandstorm and make sure it is successfully running locally.
  4. Clone this git repo.
  5. CD to the repo and make dev.
  6. Open your local Sandstorm. The app should be visible there.
  7. Ctrl+C in the terminal running make dev to disconnect.

Note: You can ignore the bogus warning about getaddrinfo and static linking -- the app will never actually call getaddrinfo. We statically link the binary so that there's no need to include shared libs in the package, making it smaller and simpler.

Note: Due to an ongoing disagreement between GCC's and Clang's interpretations of the C++ ABI, it is important that you use the same compiler to compile this example program as you use to compile Cap'n Proto. By default both will use GCC. You can run make CXX=clang++ to build with Clang instead.

Building your own

You can use this code as a starting point for your own app.

  1. Edit sandstorm-pkgdef.capnp, read the comments, and edit. At the very least you want to rename the app and set a new App ID.
  2. Place your own client code (HTML, CSS, Javascript, etc.) in the client directory.
  3. Have your client code use HTTP GET, PUT, and DELETE requests to store user data under the HTTP path /var. You can create files under /var with any name, but you cannot create sub-directories (for now).
  4. Use make dev to test.
  5. Type just make to build a distributable package package.spk.

Note that server.c++ has some "features" that you may feel inclined to modify:

Questions?

Ask on the dev group.