Skip to main content Link Search Menu Expand Document (external link)

["createHistoryStream"]

Table of contents

  1. Description
  2. Specification
    1. Requests
      1. Args
    2. Responses
      1. Without keys
      2. With keys
  3. Support table
  4. 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 truethen 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.

  • Request number:
    1
  • Stream:
    true
  • End/err:
    false
  • Body type:
    JSON
{
  "name": ["createHistoryStream"],
  "type": "source",
  "args": [
    {
      "id": "@FCX/tsDLpubCPKKfIrw4gc+SQkHcaD17s7GI6i/ziWY=.ed25519",
      "keys": false
    }
  ]
}
  • Request number:
    -1
  • Stream:
    true
  • End/err:
    false
  • Body type:
    JSON
{
  "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.

  • Request number:
    2
  • Stream:
    true
  • End/err:
    false
  • Body type:
    JSON
{
  "name": ["createHistoryStream"],
  "type": "source",
  "args": [
    {
      "id": "@FCX/tsDLpubCPKKfIrw4gc+SQkHcaD17s7GI6i/ziWY=.ed25519",
      "keys": true
    }
  ]
}
  • Request number:
    -2
  • Stream:
    true
  • End/err:
    false
  • Body type:
    JSON
{
  "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

  • Request number:
    1
  • Stream:
    true
  • End/err:
    false
  • Body type:
    JSON
go-ssb v0.2.1
{
    "name": ["createHistoryStream"],
    "args": [
        {
            "keys": false,
            "limit": -1,
            "id": "@CIlwTOK+m6v1hT2zUVOCJvvZq7KE/65ErN6yA2yrURY=.ed25519",
            "seq": 1
        }
    ],
    "type": "source"
}

Patchwork

  • Request number:
    1
  • Stream:
    true
  • End/err:
    false
  • Body type:
    JSON
Patchwork 3.18.1
    {
        "name": ["createHistoryStream"],
        "args": [
            {
                "id": "@qFtLJ6P5Eh9vKxnj7Rsh8SkE6B6Z36DVLP7ZOKNeQ/Y=.ed25519",
                "seq": 79,
                "live": true,
                "keys": false,
            }
        ],
        "type": "source"
    }

Server terminations

Manyverse

  • Request number:
    -1
  • Stream:
    true
  • End/err:
    true
  • Body type:
    JSON
Manyverse v0.2203.21-beta
true