feat: add api to get stream state

[nathanielc]

With this change it is now possible to get the current state of a stream via the HTTP JSON API.

Fixes #581

[dav1do]

Nice, looks good. A couple small comments and looks like there's a format issue to resolve but nothing major from me.

[stbrody]

"State" feels overloaded here.

"content" of the stream?

[nathanielc]

Its not the content, its both the metadata and the data (previously called content). Maybe we should call this state, metadata, content?

The state is currently defined as:

struct State{
   metadata: Object,
   data: Object,
}

[stbrody]

hmm, the problem is this whole structure is called StreamState. Having a field called state inside a struct called StreamState feels confusing to me. Now when we hear the word "state" we don't know if we mean the inner field or the outer structure.

Its not the content, its both the metadata and the data

I think this isn't true, since there is already a different metadata field at the top level here. So having metadata and data at the top level avoids the need to expose anything called "state" to the user at all.

I don't love that internally we call the pair of metadata and data "state", but at least that's hidden as an internal implementation detail. If we can keep that concept out of the public API that might be good enough for now.

[nathanielc]

I see the confusion, let me see if I can make the table structure mirror the flattened structure of this StreamState object more closely.

[nathanielc]

The trouble here is keeping this API generic to stream types. Metadata is a property of the MID stream type. That is causing the problems here. I say we leave metadata and data as opaque to this API

How does this look as a definition of the StreamState:

    StreamState:
      title: State of a Ceramic stream
      description: The state of a Ceramic stream as defined by the stream type aggregation and conflict resolution rules.
      type: object
      required:
        - id
        - event_cid
        - controller
        - dimensions
        - data
      properties:
        id:
          type: string
          description: Multibase encoding of the stream id
        event_cid:
          type: string
          description: CID of the event that produced this state
        controller:
          type: string
          description: Controller of the stream
        dimensions:
          type: object
          description: Dimensions of the stream, each value is multibase encoded.
        data:
          type: object
          description: Data of the stream

Then data for MID streams will be an object of

{
   metadata: ...,
   content: ...,
}

Thoughts?

This way we do not overload names and uses of the existing clients will understand that content is the same as the original meaning of content.

[stbrody]

yeah that sounds good!

[nathanielc]

@stbrody Ok adjusted to match the now consistent names and structure defined in the pipeline/DESIGN.md doc.