API link in README is outdated

[Connoropolous]

Whatever the result of this issue in ssb-db is, the result of that work should be linked to as a primary API reference for this project...
ssbc/ssb-db#271

[Connoropolous]

I think a good place to link to might be right here, since this kind of explains the compounded API situation between the two...

https://github.com/ssbc/ssb-db#secretstackuserequiressb-db--secretstackapp

[christianbundy]

Alternatively, maybe the readme could link to the various APIs for all of the plugins used? I'd strongly agree that ssb-db should be the priority, since that's the most common, but it'd be cool to know which plugins are included in this distro.

[Connoropolous]

ssb-db is it, from what I can tell.

ssb-server/index.js

Lines 3 to 9 in c66ecf9

	var SSB = require('ssb-db')
	//create a sbot with default caps. these can be overridden again when you call create.
	function createSsbServer () {
	return SecretStack({ caps: { shs: Buffer.from(caps.shs, 'base64') } }).use(SSB)
	}
	module.exports = createSsbServer()

[christianbundy]

It's confusing, but you get different behavior depending on whether you call from JS or the CLI.

• From JS, you only get ssb-db.
• From the CLI, you get lots of different plugins.

There's been discussion about spinning bin.js into it's own module (ssb-cli?), but it hasn't happened yet.

[Connoropolous]

oooh, yah. Just realizing that myself too haha.

[Connoropolous]

Well hmm, that IS very confusing ...

Is it possible to dig up links to where this discussion about that idea was taking place?

[mixmix]

We need to rip out ssb-cli it's WELL past time.

[Connoropolous]

What interesting is that if you take out ssb-cli from here, not much is left.

What is the value add of ssb-server at that point?

Can either of you outline the specifics of how you'd approach the separation?

[christianbundy]

I thought about this more this morning and remembered some stuff.

I think @dominictarr's vision for this module is to be a secret-stack "distro", so you can:

$ npm install ssb-server

And then easily:

const createApp = require('ssb-server')
  .use('ssb-master')
  .use('ssb-gossip')
  .use('ssb-local')
  // etc

const app = createApp()

Note that in this model you don't actually install the plugins yourself, so you're relying on ssb-server installing them for you. Being very candid, I understand the benefits of this model but I don't really like reaching into my deep dependencies to summon plugins, so I've been using this module for two separate things:

• Starting a super basic SSB service with ssb-server start.

  This is really what I want out of this module. I want a super simple command to run on a Raspberry Pi that can start a server and output some info about the current server status/load/etc.

• Connecting to existing SSB services with ssb-server <command>.

  This is very important but I don't think it's the role of a server. Right now this is handled by bin.js, which we've previously considered ripping out as ssb-cli, but I have to admit that I've been unhappy with how unpredictable bin.js has been. I have lots of open issues on this repo, but specifically issues like this make me very hesitant to use ssb-server as a CLI interface to muxrpc.

I've taken a bit of time this morning to sketch out an idea of what I'd like SSB-CLI to look like, if anyone is interested in sharing feedback. I've basically taken ssb-client and glued it to yargs, and it seems to be working well so far.

Anyway, hopefully that's a helpful stew of context, feelings, and a prototype of what I think a solution should look like. Happy to answer questions, and of course, happy to yield NPM's ssb-cli namespace to ssb-server if we want to move forward with bin.js.

[dominictarr]

@christianbundy because ssb-server is a distribution you should use it via the command only.
applications such as patchwork and patchbay are their own distribution. They shouldn't depend on ssb-server, they should depend on on secret-stack and ssb-db and the other plugins directly, and they should run the tests for all those deps before cutting a new release. Not all of those intensions are fully realized, but that's the idea.

[Connoropolous]

@christianbundy i caught wind on ssb that you've been moving forward with that yargs strategy. Is that accurate. How do you think that might affect this project. Do you hope to replace bin.js? Or coexist? I don't really have an opinion, but am here to offer/hold the perspective of a relative newb, and opt for things based on how well theyd achieve/improve accessibility of ssb dev tools

[Connoropolous]

I find your distinction helpful @dominictarr . I recently created a small project that imported ssb-server, but I think I should import secretstack instead, since it's the library

[Connoropolous]

It's confusing, but you get different behavior depending on whether you call from JS or the CLI.

• From JS, you only get ssb-db.
• From the CLI, you get lots of different plugins.

There's been discussion about spinning bin.js into it's own module (ssb-cli?), but it hasn't happened yet.

We definitely would want to document this

[christianbundy]

Cool, thanks for the extra context @dominictarr. Maybe we should remove the module.exports = so that people can't import this via JS? Patchbay is the only client that I'm aware of that depends on ssb-server directly, but I'm sure there are others.

How do you think that might affect this project. Do you hope to replace bin.js? Or coexist? I don't really have an opinion, but am here to offer/hold the perspective of a relative newb, and opt for things based on how well theyd achieve/improve accessibility of ssb dev tools

Aside: I'm a bit anxious that this may be taken the wrong way, so please reach out if anything feels wrong or rude.

Most of the SSB libraries are maintained by everyone because we all depend on them, but when it comes to the end-user interfaces (Patchwork, Patchbay, Oasis, SSB-Server, etc), the responsibility usually falls on one or few maintainers. We're all friends and there's tons of cross-pollination, but we have our own styles and it's common to write an alternative implementation instead of asking a maintainer to merge code they aren't excited about.

In this case, I think Dominic is the maintainer for this module, and I don't think he'd be very excited about my SSB-CLI (Yargs, ESLint, promises, etc), so I sketched it out as a separate module instead of trying to replace bin.js. This does add complexity, because you have to choose which module you'd like to try, but I don't think there's a simple way to reconcile the problem without forcing consensus.

In summary: I don't want to step on any toes and I don't want to replace Dominic's vision of SSB-Server, but I'd also like to avoid asking Dominic to maintain a bunch of code he's unexcited about. I think the best solution is to just maintain an alternative implementation that I'm more excited about, but it adds some complexity for people learning the stack. I'm not sure how to solve that problem. :/

[dominictarr]

removing module.exports wouldn't be a bad idea, but might mean we'd have to rewrite some tests. hmm, actually I think I may have started that already so fewer things depend directly on ssb-server even for the tests. If we completed that we could remove module.exports from this.

[Connoropolous]

heh, the plot thickens. Now I see ssbc/ssb-bin , so @dominictarr that is a ripping out of bin.js from this repo is that correct?

So is ssb-server start to have a separate repo and command from ssb-bin? I am thinking that makes sense if I'm understanding correctly.
I found it confusing when I realized that ssb-server anything-besides-start was actually an ssb-client under the hood. Seems a bit of a circular dependency.

Doesn't seem a problem at all to have two different cli client options going though!

[dominictarr]

@Connoropolous correct. I think ssb-server should be ssb-server, ssb-bin can be a generic ssb client, that will work with any server distribution if it exposes a local server, which it usually does. patchwork, patchbay, for example both bundle their own ssb server distribution.

[Connoropolous]

so, by this reasoning, I've done roughly a sensible thing to do by switching from a require('ssb-server') to a require('secret-stack') in a bot system I'm developing, yeah?

rapid-sensemaking-framework/rsf-ssbable@ef6cf06

[dominictarr]

@Connoropolous yup

[mixmix]

I've moved to secret-stack but had been feeling guilty.

I'm honestly surprised that ssb-server is intended to only be cli. I think it's good. My main focus right now is writing documentation which is helps people know how to get started.
I might make a distro called ssb-boost!
When people are ready they can look at the source and see its just a tiny opinionated requireable wrapper with nice comments.

I'm pumped for this

[Connoropolous]

When you say "I've moved to secret-stack" is that for new projects, or have you switched for older projects you'd worked on as well?

[dominictarr]

@mixmix don't feel guilty, but PLEASE add compatibility https://github.com/ssbc/ssb-server/blob/master/package.json#L107-L117 and run compatibility in your tests https://github.com/ssbc/ssb-server/blob/master/package.json#L17 so that you run the tests for all the ssb plugins so that you know the combination you are using works.

[dominictarr]

I'm thinking of going back to the scuttlebot module name because that's clearer that it's a subjective distribution and not a generic, definitive thing.

[stale]

Is this still relevant? If so, what is blocking it? Is there anything you can do to help move it forward?