`["createHistoryStream"]`

Description
Specification
1. Requests
  1. Args
2. Responses
  1. Without keys
  2. With keys
Support table
Examples
1. Requests
  1. go-ssb
  2. Patchwork
2. Server terminations
  1. Manyverse

Description

This request is used for replicating messages from different clients. Clients can perform ["createHistoryStream"] requests to get new messages from feeds which they are interested in. This mechanism is sometimes referred to as “legacy replication” as new replication mechanism based on ["ebt", "replicate"] is now available.

The primary documentation for this request is the Scuttlebutt Protocol Guide.

Specification

Requests

Name	["createHistoryStream"]
Type	"source"
Args	Must be an array containing exactly one object.

Args

The object within the args array must have the following schema:

Field name	Required	Type	Description
id	true	string	Id of the feed. All observed requests used the at-sign feed id format.
sequence	false	number	If specified then messages with a sequence number greater than the provided sequence number will be returned. If `old` is `true` and this parameter is not set then this means that messages starting with the first message in the feed must be returned. Some clients pass `-1` in this field instead of not setting it. Warning! In the past the name of this argument was `seq`. All clients must create requests with the name `sequence`. Client should accept both `sequence` and `seq` as the name of this argument. If a client sets both of those arguments to `sequence` and `seq` then it must be considered an error. Warning! The protocol guide specifies that messages greater than the provided sequence number should be returned. Some clients appear to return messages with a sequence number greater or equal to the provided sequence number. See this issue.
limit	false	number	Maximum number of messages to be returned. If this argument is not set then the number of returned messages is not limited.
live	false	boolean	If this argument is set to `true`then the stream will remain open and return newly received messages for this feed as they become available. If this argument is not set then it must be considered to be `false`.
old	false	boolean	If this argument is set to `true` then already available messages will be returned, presumably from the local database. If this argument is not set then it must be considered to be `true`.
keys	false	boolean	This argument controls the format of responses. See the section about responses below. If this argument is not set then it must be considered to be `true`.

Notes:

Setting live to false and old to false seems to imply that no messages will ever be returned and the stream will be closed right away.

Responses

The messages in responses must be sent sorted by the sequence number in an ascending way. The sequence numbers must come one-by-one without gaps. Each response contains one message. The format of all responses in the stream depends on the keys parameter.

Without keys

If keys is set to false then messages are directly returned in each response.

{
  "name": ["createHistoryStream"],
  "type": "source",
  "args": [
    {
      "id": "@FCX/tsDLpubCPKKfIrw4gc+SQkHcaD17s7GI6i/ziWY=.ed25519",
      "keys": false
    }
  ]
}

{
  "previous": null,
  "author": "@FCX/tsDLpubCPKKfIrw4gc+SQkHcaD17s7GI6i/ziWY=.ed25519",
  "sequence": 1,
  "timestamp": 1514517067954,
  "hash": "sha256",
  "content": {
    "type": "post",
    "text": "This is the first post!"
  },
  "signature": "QYOR/zU9dxE1aKBaxc3C0DJ4gRyZtlMfPLt+CGJcY73sv5abKK
                Kxr1SqhOvnm8TY784VHE8kZHCD8RdzFl1tBA==.sig.ed25519"
}

With keys

If keys is set to true then messages are wrapped with an additional object.

{
  "name": ["createHistoryStream"],
  "type": "source",
  "args": [
    {
      "id": "@FCX/tsDLpubCPKKfIrw4gc+SQkHcaD17s7GI6i/ziWY=.ed25519",
      "keys": true
    }
  ]
}

{
  "key": "%XphMUkWQtomKjXQvFGfsGYpt69sgEY7Y4Vou9cEuJho=.sha256",
  "value": {
    "previous": null,
    "author": "@FCX/tsDLpubCPKKfIrw4gc+SQkHcaD17s7GI6i/ziWY=.ed25519",
    "sequence": 1,
    "timestamp": 1514517067954,
    "hash": "sha256",
    "content": {
      "type": "post",
      "text": "This is the first post!"
    },
    "signature": "QYOR/zU9dxE1aKBaxc3C0DJ4gRyZtlMfPLt+CGJcY73sv5abKK
                  Kxr1SqhOvnm8TY784VHE8kZHCD8RdzFl1tBA==.sig.ed25519"
  },
  "timestamp": 1514517067956
}

The object must have the following schema:

Field name	Required	Type	Description
key	true	string	Id of the message. All observed requests used the percent-sign feed id format.
value	false	Raw JSON	Raw JSON of the returned message.
timestamp	false	number	Unix timestamp in number of milliseconds which specifies when this message was returned by the client responding to the request.

Support table

	Sends	Accepts
go-ssb	v0.2.1 Yes.	v0.2.1 Yes.
Patchwork	3.18.1 Yes.	3.18.1 Yes. See protocol-guide/#65 for information about the `sequence` argument.
Manyverse	v0.2203.21-beta Unknown.	v0.2203.21-beta Unknown.

Examples

Requests

go-ssb

{
    "name": ["createHistoryStream"],
    "args": [
        {
            "keys": false,
            "limit": -1,
            "id": "@CIlwTOK+m6v1hT2zUVOCJvvZq7KE/65ErN6yA2yrURY=.ed25519",
            "seq": 1
        }
    ],
    "type": "source"
}

Patchwork

    {
        "name": ["createHistoryStream"],
        "args": [
            {
                "id": "@qFtLJ6P5Eh9vKxnj7Rsh8SkE6B6Z36DVLP7ZOKNeQ/Y=.ed25519",
                "seq": 79,
                "live": true,
                "keys": false,
            }
        ],
        "type": "source"
    }

Server terminations

Manyverse

true

["createHistoryStream"]

Table of contents

Description

Specification

Requests

Args

Responses

Without keys

With keys

Support table

Examples

Requests

go-ssb

Patchwork

Server terminations

Manyverse

`["createHistoryStream"]`