HistoryCommand.cursor

[Amerehei]

What is cursor in the HistoryCommand

a cursor ID for the next commands subscription

What does it mean and how can I use it?

[kkoechley]

Hi @Amerehei,

With our graphQL subscriptions, you can use the cursor from the last known subscription event as an optional argument to return all the events from the last cursor.

If you want to know the timestamp of the cursor - you can decode it with a jwt decoder.

For example:

1. sample initial subscription connection:

subscription mySubscriptionTest($workspaceId:String! ){
  commands(workspaceId:$workspaceId){
    __typename
    ... on CreateElementCommand{
      __typename
      workspaceId
      actorId
      actorType
      clientId
      cursor
      element{
        __typename
        id
        boundingBox{
          x
          y
          width
          height
        }
        traits
        reactions{
          id
          type
          unicode
          actorId
        }
        
      }
    }
    
    ... on UpdateElementCommand{
      workspaceId
      elementId
      cursor
      actorId
      actorType
      clientId
      
      data{
        __typename
        ... on UpdateShape{
          transform{
            x y
          }
        }
      }
    }
  }
}

with sample event returned:

{
  "data": {
    "commands": {
      "workspaceId": "bEu943lPQw7XWeh1pPHN",
      "elementId": "65145384d8f0dc63063907f1",
      "cursor": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjE2OTU4MzEyMTQ3MzktMCIsImV4cCI6MTY5NTkxNzYxNH0.vr7yR5rtn_cFjkqlZ0V05QeuJ4DlxlKvdqKbv9WDd1M",
      "actorId": "BC0i0wzZ5Caph7i871Ka",
      "actorType": "USER",
      "clientId": "651452e5394b730017bf684b",
      "data": {
        "__typename": "UpdateShape",
        "transform": {
          "x": -401,
          "y": -179
        }
      }
    }
  }
}

2. You can then store the cursor, or decode the cursor with jwt decoder:
   "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjE2OTU4MzEyMTQ3MzktMCIsImV4cCI6MTY5NTkxNzYxNH0.vr7yR5rtn_cFjkqlZ0V05QeuJ4DlxlKvdqKbv9WDd1M"

decoded is:

{
  "id": "1695831214739-0",
  "exp": 1695917614
}

exp is in epoch format, 1695917614, or:
Thu Sep 28 2023 18:13:34 GMT+0200 (Central European Summer Time)

3. If you want to get all the events that you missed since Thu Sep 28 2023 18:13:34 GMT+0200 (Central European Summer Time), simply add the cursor when reconnecting:

subscription mySubscriptionTest($workspaceId:String! ){
  commands(workspaceId:$workspaceId, cursor:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjE2OTU4MzEyMTQ3MzktMCIsImV4cCI6MTY5NTkxNzYxNH0.vr7yR5rtn_cFjkqlZ0V05QeuJ4DlxlKvdqKbv9WDd1M"){
    __typename
    ... on CreateElementCommand{
      __typename
      workspaceId
      actorId
      actorType
      clientId
      cursor
      element{
        __typename
        id
        boundingBox{
          x
          y
          width
          height
        }
        traits
        reactions{
          id
          type
          unicode
          actorId
        }
        
      }
    }
    
    ... on UpdateElementCommand{
      workspaceId
      elementId
      cursor
      actorId
      actorType
      clientId
      
      data{
        __typename
        ... on UpdateShape{
          transform{
            x y
          }
        }
      }
    }
  }
}

The response will return all events from the cursor time, and maintain the subscription socket connection to also stream any new events.

[Amerehei]

It’s a very nice feature! thanks

[kkoechley]

Thanks for the feedback and great questions!