git ssb

2+

cel / scuttlebot.io



Commit 13691e1ee2bb8b8cec137e18d9f495648fba6793

Browse Files

add message-type docs

Paul Frazee committed on 3/16/2016, 3:19:06 AM
Parent: 88cc22ff535622f9d4c218ca12f0d920febd8429

Files changed

tmpl/apis/pull-stream/pull-stream.mdchanged
tmpl/css/index.css.jschanged
tmpl/docs/message-types/about.html.jschanged
tmpl/docs/message-types/contact.html.jschanged
tmpl/docs/message-types/post.html.jschanged
tmpl/docs/message-types/pub.html.jschanged
tmpl/docs/message-types/vote.html.jschanged
tmpl/docs/message-types/about.mdadded
tmpl/docs/message-types/contact.mdadded
tmpl/docs/message-types/custom-types.html.jsadded
tmpl/docs/message-types/custom-types.mdadded
tmpl/docs/message-types/post.mdadded
tmpl/docs/message-types/pub.mdadded
tmpl/docs/message-types/vote.mdadded
tmpl/leftnav.part.jschanged
tmpl/page.part.jschanged
tmpl/apis/pull-stream/pull-stream.mdView
@@ -5,9 +5,9 @@
55 In [classic-streams](1),
66 streams _push_ data to the next stream in the pipeline.
77 In [new-streams](https://github.com/joyent/node/blob/v0.10/doc/api/stream.markdown),
88 data is pulled out of the source stream, into the destination.
9-In [new-classic-streams](
9+
1010 `pull-stream` is a minimal take on streams,
1111 pull streams work great for "object" streams as well as streams of raw text or binary data.
1212
1313
tmpl/css/index.css.jsView
@@ -21,8 +21,13 @@
2121 }
2222 pre code {
2323 white-space: pre-wrap;
2424 }
25+code {
26+ background: #eee;
27+ padding: 0 0.5em;
28+ font-size: 0.9em;
29+}
2530
2631 p {
2732 line-height: 1.5;
2833 }
tmpl/docs/message-types/about.html.jsView
@@ -1,10 +1,15 @@
1+var md = require('../../../markdown')
12 var page = require('../../page.part')
23 module.exports = () => page({
34 section: 'docs',
45 tab: 'docs-message-types',
5- path :'/docs/message-types/about.html',
6- content: `
7- <h2>About</h2>
8- <p>todo</p>
9- `
6+ path: '/docs/message-types/about.html',
7+ content: md.doc(__dirname+'/about.md'),
8+ seeAlso: [
9+ ['/docs/social/update-your-profile.html', 'Update your profile'],
10+ ['/docs/advanced/message-schemas.html', 'Message schemas'],
11+ ['/docs/advanced/linking-messages.html', 'Linking messages'],
12+ ['/apis/modules/ssb-msg-schemas.html', 'SSB-Msg-Schemas API']
13+ ],
14+ next: ['./contact.html', 'Contact']
1015 })
tmpl/docs/message-types/contact.html.jsView
@@ -1,10 +1,14 @@
1+var md = require('../../../markdown')
12 var page = require('../../page.part')
23 module.exports = () => page({
34 section: 'docs',
45 tab: 'docs-message-types',
5- path :'/docs/message-types/contact.html',
6- content: `
7- <h2>Contact</h2>
8- <p>todo</p>
9- `
6+ path: '/docs/message-types/contact.html',
7+ content: md.doc(__dirname+'/contact.md'),
8+ seeAlso: [
9+ ['/docs/advanced/message-schemas.html', 'Message schemas'],
10+ ['/docs/advanced/linking-messages.html', 'Linking messages'],
11+ ['/apis/modules/ssb-msg-schemas.html', 'SSB-Msg-Schemas API']
12+ ],
13+ next: ['./vote.html', 'Vote']
1014 })
tmpl/docs/message-types/post.html.jsView
@@ -1,10 +1,14 @@
1+var md = require('../../../markdown')
12 var page = require('../../page.part')
23 module.exports = () => page({
34 section: 'docs',
45 tab: 'docs-message-types',
5- path :'/docs/message-types/post.html',
6- content: `
7- <h2>Post</h2>
8- <p>todo</p>
9- `
6+ path: '/docs/message-types/post.html',
7+ content: md.doc(__dirname+'/post.md'),
8+ seeAlso: [
9+ ['/docs/advanced/message-schemas.html', 'Message schemas'],
10+ ['/docs/advanced/linking-messages.html', 'Linking messages'],
11+ ['/apis/modules/ssb-msg-schemas.html', 'SSB-Msg-Schemas API']
12+ ],
13+ next: ['./about.html', 'About']
1014 })
tmpl/docs/message-types/pub.html.jsView
@@ -1,10 +1,14 @@
1+var md = require('../../../markdown')
12 var page = require('../../page.part')
23 module.exports = () => page({
34 section: 'docs',
45 tab: 'docs-message-types',
5- path :'/docs/message-types/pub.html',
6- content: `
7- <h2>Pub</h2>
8- <p>todo</p>
9- `
6+ path: '/docs/message-types/pub.html',
7+ content: md.doc(__dirname+'/pub.md'),
8+ seeAlso: [
9+ ['/docs/advanced/message-schemas.html', 'Message schemas'],
10+ ['/docs/advanced/linking-messages.html', 'Linking messages'],
11+ ['/apis/modules/ssb-msg-schemas.html', 'SSB-Msg-Schemas API']
12+ ],
13+ next: ['./custom-types.html', 'Custom Types']
1014 })
tmpl/docs/message-types/vote.html.jsView
@@ -1,10 +1,14 @@
1+var md = require('../../../markdown')
12 var page = require('../../page.part')
23 module.exports = () => page({
34 section: 'docs',
45 tab: 'docs-message-types',
5- path :'/docs/message-types/vote.html',
6- content: `
7- <h2>Vote</h2>
8- <p>todo</p>
9- `
6+ path: '/docs/message-types/vote.html',
7+ content: md.doc(__dirname+'/vote.md'),
8+ seeAlso: [
9+ ['/docs/advanced/message-schemas.html', 'Message schemas'],
10+ ['/docs/advanced/linking-messages.html', 'Linking messages'],
11+ ['/apis/modules/ssb-msg-schemas.html', 'SSB-Msg-Schemas API']
12+ ],
13+ next: ['./pub.html', 'Pub']
1014 })
tmpl/docs/message-types/about.mdView
@@ -1,0 +1,37 @@
1+## About
2+
3+About-messages set attributes about someone or something.
4+They can be used to set a name or picture for users, files, or messages.
5+However, they're most commonly published about users.
6+
7+About messages do not have to have both `name` and `image`, and, in fact, it's recommended that they only have one or the other.
8+Why?
9+Because then a `vote` on the message can be more specific.
10+
11+```js
12+{ type: 'about', about: Link, name: String, image: BlobLink }
13+```
14+
15+### Names
16+
17+There's no global registry of names.
18+Each user can choose a name for themselves and for others, and conflicts are allowed.
19+
20+Its up to your application to decide which names to use.
21+Generally speaking, names by followed users are trusted, and the local user gets to override all decisions.
22+
23+A common rule for names is to allow `A-z0-9._-`, and not allow a trailing `.`.
24+
25+### Images
26+
27+For images, a common size is 512x512.
28+Square images are recommended but not required.
29+
30+Some recommended (but not required) attributes on the `image` link:
31+
32+ - `width` in pixels
33+ - `height` in pixels
34+ - `name` a string filename
35+ - `size` in bytes
36+ - `type` a mimetype
37+
tmpl/docs/message-types/contact.mdView
@@ -1,0 +1,12 @@
1+## Contact
2+
3+Contact-messages determine who you are following or blocking.
4+
5+```js
6+{
7+ type: 'contact',
8+ contact: FeedLink,
9+ following: Bool,
10+ blocking: Bool
11+}
12+```
tmpl/docs/message-types/custom-types.html.jsView
@@ -1,0 +1,14 @@
1+var md = require('../../../markdown')
2+var page = require('../../page.part')
3+module.exports = () => page({
4+ section: 'docs',
5+ tab: 'docs-message-types',
6+ path: '/docs/message-types/custom-types.html',
7+ content: md.doc(__dirname+'/custom-types.md'),
8+ seeAlso: [
9+ ['/docs/advanced/message-schemas.html', 'Message schemas'],
10+ ['/docs/advanced/linking-messages.html', 'Linking messages'],
11+ ['/apis/modules/ssb-msg-schemas.html', 'SSB-Msg-Schemas API']
12+ ],
13+ next: ['/docs/advanced/advanced-queries.html', 'Advanced queries']
14+})
tmpl/docs/message-types/custom-types.mdView
@@ -1,0 +1,23 @@
1+## Custom Types
2+
3+Message schemas are interpretted according to the `type` attribute, as demonstrated in the other pages of this section.
4+
5+There is no restriction on which types applications use.
6+A `type` simply must be a string between 3 and 52 characters long.
7+You are free to create new types, with their own schemas, as you need them.
8+
9+However, it's important for applications to interpret messages the same way.
10+Otherwise, they won't be able to interoperate.
11+
12+Likewise, it's important to interpret messages "defensively."
13+There's nothing enforcing a schema, so (as with any input) applications must be prepared for malformed `content` objects in messages.
14+
15+### Interoperation
16+
17+There is no official mechanism for making sure message-types interoperate, except for the documentation which you're reading here.
18+As it becomes clear that new types are coming into common use, we'll add them to this site.
19+
20+### Namespacing
21+
22+To avoid accidental collisions with other applications, it's a good idea to add your org or application name (or both!) to the message type.
23+We recommend: `{org}-{app}-{type}`, or `{app}-{type}` if you think your app has a very unique name.
tmpl/docs/message-types/post.mdView
@@ -1,0 +1,51 @@
1+## Post
2+
3+A post is a text-based message, for a public or private audience.
4+It can be a reply to other posts.
5+
6+There's not a limit on the length of the text, but all Scuttlebot messages (including their headers) must be less than 8KB.
7+
8+```js
9+{
10+ type: 'post',
11+ text: String,
12+ channel: String?,
13+ root: MsgLink?,
14+ branch: MsgLink?,
15+ recps: FeedLinks?,
16+ mentions: Links?
17+}
18+```
19+
20+### Text
21+
22+`text` is a markdown string that includes the body of the post.
23+See [SSB-Markdown](/apis/modules/ssb-markdown.html) for some Scuttlebot-specific markdown rules.
24+
25+### Channel
26+
27+`channel` is optionally used for categorization.
28+It's similar to subreddits or chat channels.
29+
30+### Root and branch
31+
32+`root` and `branch` are for replies.
33+`root` should point to the topmost message in the thread.
34+`branch` should point to the message in the thread which is being replied to.
35+
36+In the first reply of a thread, `root === branch`, and both should be included.
37+`root` and `branch` should only point to `type: post` messages.
38+If the post is about another message-type, use `mentions`.
39+
40+### Mentions
41+
42+`mentions` is a generic reference to other feeds, entities, or blobs.
43+
44+ - User mentions: for when a user is referenced in the `text`.
45+ - Blob mentions: for when a file is referected in the `text`.
46+ - Message mentions: for when a message is referenced in the `text`.
47+
48+### Recps
49+
50+`recps` is a list of user-links specifying who the message is for.
51+This is typically used for encrypted messages, to specify who the message was encrypted for, but it can be used in unencrypted messages as well.
tmpl/docs/message-types/pub.mdView
@@ -1,0 +1,17 @@
1+## Pub
2+
3+Pub-messages announce the ID, address, and port of public Pub users.
4+They are automatically published by Scuttlebot after successfully using an invite to a Pub.
5+
6+When Scuttlebot sees a pub-message, it will add the link/host/port triple to its peers table, and connect to the peer in the future to sync messages.
7+
8+```js
9+{
10+ type: 'pub',
11+ pub: {
12+ link: FeedLink,
13+ host: String,
14+ port: Number
15+ }
16+}
17+```
tmpl/docs/message-types/vote.mdView
@@ -1,0 +1,41 @@
1+## Vote
2+
3+Vote-messages signal approval about someone or something.
4+Votes can be on users, messages, or blobs.
5+
6+The `value` should be negative, 0, or positive.
7+If the value is non-numeric, it is invalid.
8+
9+The `reason` is an optional string to explain the vote.
10+
11+```js
12+{
13+ type: 'vote',
14+ vote: {
15+ link: Link,
16+ value: -1|0|1,
17+ reason: String?
18+ }
19+}
20+```
21+
22+### Voting on users
23+
24+A positive vote on a user signals trust in that user.
25+It's generally used to "confirm" that you think that user publishes good information.
26+
27+A negative vote on a user is a "flag."
28+You can flag a user for publishing bad information, making false claims, or being abusive.
29+You can also flag a user if the owner lost the keys.
30+
31+Common values for `reason` in downvotes on users:
32+
33+ - `dead`: Dead Account / Lost Keys
34+ - `spam`: Spammer
35+ - `abuse`: Abusive behavior
36+
37+### Voting on messages/blobs
38+
39+A positive vote on a message or blobs signals that you like the content of the message/blobs.
40+
41+A negative vote on a message is a "flag" that signals that you think the message/blob content should not be used or seen.
tmpl/leftnav.part.jsView
@@ -28,13 +28,13 @@
2828 ${item(c, '/docs/message-types/about.html', 'About')}
2929 ${item(c, '/docs/message-types/contact.html', 'Contact')}
3030 ${item(c, '/docs/message-types/vote.html', 'Vote')}
3131 ${item(c, '/docs/message-types/pub.html', 'Pub')}
32+ ${item(c, '/docs/message-types/custom-types.html', 'Custom Types')}
3233 </ul>`
3334
3435 module.exports['docs-advanced'] = (c) => `<ul class="nav">
3536 ${item(c, '/docs/advanced/advanced-queries.html', 'Advanced queries')}
36- ${item(c, '/docs/advanced/pull-streams.html', 'Pull streams')}
3737 ${item(c, '/docs/advanced/message-schemas.html', 'Message schemas')}
3838 ${item(c, '/docs/advanced/linking-messages.html', 'Linking messages')}
3939 ${item(c, '/docs/advanced/crdts.html', 'CRDTs')}
4040 </ul>`
tmpl/page.part.jsView
@@ -18,8 +18,15 @@
1818 // pick the navs
1919 var tabFn = tabs[opts.section || 'docs']
2020 var leftnavFn = leftnav[opts.tab || 'basics']
2121
22+ // next and see-also
23+ var seeAlso = '', next = ''
24+ if (opts.seeAlso)
25+ seeAlso = `<ul class="see-also">` + opts.seeAlso.map(item => `<li><a href="${item[0]}">${item[1]}</a></li>`).join('') + `</ul>`
26+ if (opts.next)
27+ next = `<p class="next"><a href="${opts.next[0]}">${opts.next[1]}</a></p>`
28+
2229 // render the page
2330 return `<html>
2431 ${head()}
2532 <body>
@@ -29,8 +36,10 @@
2936 <div class="nav-content-unit">
3037 ${leftnavFn(opts.path)}
3138 <div class="content">
3239 ${opts.content}
40+ ${seeAlso}
41+ ${next}
3342 </div>
3443 </div>
3544 ${footer(opts.path)}
3645 </body>

Built with git-ssb-web