sandstorm-http-bridge docs

[dmitry-sher]

We are currently trying to adapt our Meteor.js apps for Sandstorm. Unfortunately, for me docs are very confusing and they do not answer some very basic questions.

When I create some API, i provide at least a list of endpoints and relevant parameters.

For app creator, sandstorm-http-bridge is pretty much an API. What endpoints does it have? What parameters should I pass and in a which way?

For example: i want to request getViewInfo from grain, shared to me, in Meteor.js app. How should i do that? The Collections app uses raw cap'n'proto with Rust and i just don't so much c++ person to understand direct links to sandstorm-http-bridge.c++

What other places are good for asking such questions?

[dmitry-sher]

One endpoint directly mentioned in docs:

http://http-bridge/session/${sessionId}/claim

Ok, nice. What are other endpoints?

How to call getViewInfo, what parameters should i pass and in a which way?

Should i understand this by reading capnp files somehow?...

[dmitry-sher]

Please give me some help. Or guide me to some direction. I'm struggling with this for second week now. I'm an experienced JS developer with 10+ years of experience and I feel that i simply don't understand some very basics about this Cap'n'proto thing. We are very big fans of Sandstorm as an idea, but the lack of relevant docs is very frustrating.

I'm ready to transform my experiences into nice tutorial. What i want to create: basic Meteor.js app, that is connecting to other grains and exchanging some data thru HTTP(s) API between them. I have a plan like this. (+) is set on parts that i managed to do already, (-) on totally not understood topics, (*) on partially understood but not yet implemented parts.

+0. Preparing developer environment (Linux Ubuntu 16.04 x64 VM with right kernel, connect it to host with sshfs, install relevant VSCode plugins etc) +1. Creating a modern Meteor 1.4/1.5+React project +2. Filling in basic sandstorm-pkgdef info +3. Opening your app as an grain in dev mode for the first time +4. Understanding how choose your app in Powerbox. Creating Powerbox descriptors for your app and packing them to base64. +5. Parsing the results of PowerBox request and claiming tokens. -6. Collecting basic info about shared grains (title, icon). 7. Exporting HTTP API from your app. 8. Calling HTTP API of other app from your grain. -9. Finishing your sandstorm-pkgdef -10. Packaging your app -11. Sending your app to app market.

All this in nice, clean, linted ES7 Javascript. As a shared github repo with commits for each step.

I think it would be very nice for community. If anybody is willing to help me, i would be tremendously happy. We can connect thru skype (dmitry.sher) or this github account.

[ocdtrekkie]

I am usually pretty helpful on the steps 9-11 here. :)

OwnTracks not only has the apiPath in it's sandstorm-pkgdef file, but it looks like they left all of the comments from bridgeConfig in there, so it might be useful to glance at: https://github.com/mnutt/owntracks-recorder/blob/master/.sandstorm/sandstorm-pkgdef.capnp

I think one of the issues is that a lot of the powerbox features came right after Sandstorm-the-company spun down, which is why nobody has written docs yet. (Most of the docs for features existing while they had employees are decent.) If you can find the source file where the feature is implemented, Kenton does a lot of documentation via comments, that really just need to be translated into actual documentation pages for the docs site.

[kentonv]

Unfortunately, the things the Collection app does can really only be done at the Cap'n Proto level today. I have wanted to add HTTP-level APIs via the outgoing HTTP proxy that sandstorm-http-bridge sets up, but haven't done that yet. (Currently the HTTP proxy supports apps connecting to HTTP APIs from other apps, but not managing grains and sharing like the Collections app does.)

sandstorm-http-bridge does provide direct access to some of the capnp API surface, though. See sandstorm-http-bridge.capnp for starters. You can connect to this API via the Cap'n Proto RPC protocol, connecting to the Unix domain socket /tmp/sandstorm-api.

For an example of a node.js Sandstorm app that uses sandstorm-http-bridge but also uses Cap'n Proto APIs, see Etherpad, specifically this file:

https://github.com/kentonv/etherpad-lite/blob/sandstorm/src/node/handler/SandstormHandler.js

Or for a Meteor app doing the same, look at Wekan:

https://github.com/wekan/wekan/blob/master/sandstorm.js

The .capnp files are not covered in much detail in the Sandstorm docs, but they have extensive comments inside the files themselves.