16:06 <abliss> am I the only one thoroughly confused by offerTemplates, webkeys, HackSessionContext, and http-bridge? i've lost track of what's deprecated and what's not ready yet.

16:07 <abliss> (i don't have specific questions; the docs seem very readable on the micro scale. i just don't at all grok the big picture)

16:19 <abliss> oh maybe here's a specific question. check out gitweb-pages https://github.com/paulproteus/gitwebpages-sandstorm/blob/master/post-receive-hook.sh#L10 . After a git push, it calls getPublicId with the session id to get the public id. But does the publicId depend on the session id? I'm assuming not, or else you'd have to update your dns records after every push. So, why is it required?

16:21 <abliss> There's similar code to get a publicId in cgi from the session-id of the browser : https://github.com/paulproteus/gitwebpages-sandstorm/blob/master/srv/http/gitweb/gitweb.cgi#L1543 presumably it always gives the same answer, regardless of whether the session is a web browser or a git client's api call

16:22 <abliss> since a publicId presumably never expires, is it safe to request it once (when the user elects to publish) and then store it in the app's data files?

16:22 <abliss> (and is there a way to unpublish a publicId?)

16:29 <abliss> and, again assuming the session-id doesn't matter, is there a way to get the grain's publicId once when the grain is created (e.g. in start.sh) rather than when it's first visited?

16:38 <abliss> also, the vagrant-spk docs reference `launcher.sh` but I seem to have `start.sh` and `continue.sh`; which is newer?

16:47 <abliss> also, looks like debian/contrib-stretch only has capnproto v0.5.3 which is too old to build getPublicId? anyone know if there are plans to release 0.6.1+ to strech?

19:41 <ocdtr_web> abliss: spk defaults to the start.sh and continue.sh nomenclature, I believe. Whereas vagrant-spk likes to use launcher.sh. I think this is because it was very rare that someone ended up using different initial and subsequent commands to launch a grain.

19:43 <ocdtr_web> Since which sh commands you run when launching a grain are defined in the pkgdef, it doesn't really matter which flavor you use.

19:43 <ocdtr_web> In the case of GitWeb, I believe GitWeb was converted from spk to vagrant-spk, whereas GitWeb Pages was and remained plain spk.

19:45 <ocdtr_web> I'd like to get vagrant-spk out as 1.0 with stretch as the box of choice, but we probably need to talk about moving past stretch at some point too, and eventually making it less painful to upgrade boxes.

19:46 <ocdtr_web> You could use contrib-buster64 and since GitWeb wasn't using anything but the diy stack, it probably (hopefully) won't break anything.

19:51 <ocdtr_web> Basically as long as you have a 64-bit contrib- box which has vboxsf support, vagrant-spk shouldn't, in theory, choke on it. Some of the stacks might just try to install packages for the wrong versions and the like.

20:58 <isd> I think "very readable on a micro scale" is a pretty good summary of the quality of our docs. The big picture is a bit lacking.

21:04 <isd> But I think some of this is not even a docs issue: we just have too many one-off mechanisms. Some of these will get replaced wth the powerbox and we can just hit delete on the old docs (or move them off in the corner with legacy stuff).

21:04 <isd> I'd like to see the current web-publishing mechanism get replaced with something powerbox-based.

21:05 <isd> But the question of how "public" content works should probably get thought about in parallel. Half the reason web publishing is so hacky is that it pre-dates our unified mechanism for requesting access to stuff, the other half is that doing "public" anything is still an open question.

21:12 <isd> ...a lot of the stuff in the web publishing docs is also just out of date wrt. where we are on other platform features.

21:13 <isd> At some point we should just go through and find all the places that say the powerbox isn't implemented yet and fix them, I know there are a bunch.

21:14 <ocdtr_web> I am just happy we now have the technical capability to update the docs at all. \o/

21:17 <isd> Hooray!

21:18 <isd> You know what, I'm going to do some grepping. Good warmup task.

21:18 <ocdtr_web> I, for one, would like to see developer docs broken out a bit into spk and vagrant-spk sections (a docker-spk section someday?) and then a section for accessing and using Sandstorm APIs/Powerbox.

21:19 <ocdtr_web> I was thinking about linking your hello-oauth example somewhere in the docs as well. Sometimes the paper doc is not nearly as easy for someone to wrap their head around then working code they can monkey with.

21:19 <isd> Yeah, we need higher-level organization in general.

21:20 <isd> But building/packagings vs. talking to the platform is a good subdivision.

21:20 <isd> Probably my example should be linked from the docs I was referring to when I built it :P

21:21 <isd> Also, we should probably be distributing `static/rpc.mjs`; it's going to be useful for any app that makes these requests.

21:22 <isd> There's no reason each app developer should have to write that

21:27 <ocdtr_web> I think it's highly likely that a lot of people looking to make these requests are going to start by copy/pasting your code and modifying it anyways. ;)

21:29 <isd> Sure. But as a developer myself, I want to be able to just `import {powerBoxRequest} from 'sandstorm-client-rpc'`, rather than copying-and pasting. So I guess I should make an npm package.

21:30 <isd> I should probably figure out how publishing stuff to npm works.

21:32 <ocdtr_web> Only helps if you're using Node for your app.

21:33 <isd> Well, this is client-side code, so "node" is irrelevant. But npm is commonly used to do package management for stuff with substantial client-side code.

21:34 <isd> Another option: embed the thing in sandstorm-http-bridge, so you can include it by just adding a script tag that references it, without actually adding it yourself.

21:34 <ocdtr_web> I have wondered about if something like vagrant-spk should have handy tools/drop-ins to help build apps in Sandstorm or something. Since it is less "the app platform" and more "a cheap framework that helps you build apps with the app platform", it might not be an unreasonable place for things we don't necessarily want to embed in Sandstorm itself

21:34 <ocdtr_web> but do want to make handy for app devs.

21:35 <isd> I think we're going to find more cases where we'd like to be able to package up some logic that goes on the app-side of the sandbox. It'd be nice to have a general story about how to do that.

21:36 <isd> Right now we've got "add it to the bridge" basically.

21:36 <ocdtr_web> The nice thing about "add it to the bridge" is that then it is generally specified in the bridgeConfig in pkgdef, which is a nice/handy way to see what an app can do.

21:39 <isd> Yeah. I'm not sure letting the bridge just become the unprivileged half of the app platform is the wrong thing.

21:40 <isd> I kinda think the docs as written are overly enthusiastic about apps that don't use the bridge. I don't see this as something that anybody ever does.

21:40 <isd> ...I say this as someone who tried.

21:41 <isd> We should make sure there are open issues for each of the provisional apis that we want to replace with the powerbox.

21:41 <isd> So email, web publishing, anything else?

21:42 <ocdtr_web> Is there some particular downside to using the bridge?

21:42 <isd> Not really.

21:42 <isd> Well, once #3027 is fixed.

21:42 <isd> There might be a few other ways in which it's "in the way" -- I'm not sure.

21:42 <isd> But there's no fundamental reason.

21:43 <ocdtr_web> Then ¯\_(ツ)_/¯

21:43 <isd> The docs kinda talk about it as though native apps are preferred somehow. And that's kinda my point -- they shouldn't be.

21:43 <isd> "native"

21:44 <ocdtr_web> There might be a magical day when a bunch of people really really want to write apps that will only ever work in Sandstorm and do the legwork to not use the bridge.

21:44 <ocdtr_web> But that is not this day.

21:44 <ocdtr_web> (I recall a window of time when apps written for HTTP instead of Sandstorm itself were referred to as "legacy" apps. I feel that was a tad optimistic.)

21:44 <isd> Really the problem with not using it is web-session, otherwise it'd be fine.

21:45 <isd> See also: https://github.com/sandstorm-io/sandstorm/issues/3174

21:47 <isd> I think what web-session buys us is essentially: https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/

21:47 <isd> So it's useful from a building-sandstorm perspective, but I think app developers should basically think of it as internals

22:21 <isd> Re: docs, I think we ought to put the capnp stuff somewhere more prominent. A lot of the docs are just in those files, and while that's fine, it's kinda silly for developers to have to go dig into some subdirectory in the sandstorm source repo.

22:21 <isd> Also, half those files are relevant to app developers, while the other half are internal interfaces not used by apps.

22:21 <isd> And there's a bunch of C++ source in the same directory.

22:24 <isd> Also, I get the vibe that folks don't think to look at the capnp specs to understand the platform.