github.com/Finschia/finschia-sdk@v0.48.1/store/streaming/README.md (about)

     1  # State Streaming Service
     2  This package contains the constructors for the `StreamingService`s used to write state changes out from individual KVStores to a
     3  file or stream, as described in [ADR-038](../../docs/architecture/adr-038-state-listening.md) and defined in [types/streaming.go](../../baseapp/streaming.go).
     4  The child directories contain the implementations for specific output destinations.
     5  
     6  Currently, a `StreamingService` implementation that writes state changes out to files is supported, in the future support for additional
     7  output destinations can be added.
     8  
     9  The `StreamingService` is configured from within an App using the `AppOptions` loaded from the app.toml file:
    10  
    11  ```toml
    12  [store]
    13      streamers = [ # if len(streamers) > 0 we are streaming
    14          "file", # name of the streaming service, used by constructor
    15      ]
    16  
    17  [streamers]
    18      [streamers.file]
    19          keys = ["list", "of", "store", "keys", "we", "want", "to", "expose", "for", "this", "streaming", "service"]
    20          write_dir = "path to the write directory"
    21          prefix = "optional prefix to prepend to the generated file names"
    22  ```
    23  
    24  `store.streamers` contains a list of the names of the `StreamingService` implementations to employ which are used by `ServiceTypeFromString`
    25  to return the `ServiceConstructor` for that particular implementation:
    26  
    27   
    28  ```go
    29  listeners := cast.ToStringSlice(appOpts.Get("store.streamers"))
    30  for _, listenerName := range listeners {
    31      constructor, err := ServiceTypeFromString(listenerName)
    32      if err != nil {
    33      	// handle error
    34      }
    35  }
    36  ```
    37  
    38  `streamers` contains a mapping of the specific `StreamingService` implementation name to the configuration parameters for that specific service.
    39  `streamers.x.keys` contains the list of `StoreKey` names for the KVStores to expose using this service and is required by every type of `StreamingService`.
    40  In order to expose *all* KVStores, we can include `*` in this list. An empty list is equivalent to turning the service off.
    41  
    42  Additional configuration parameters are optional and specific to the implementation.
    43  In the case of the file streaming service, `streamers.file.write_dir` contains the path to the
    44  directory to write the files to, and `streamers.file.prefix` contains an optional prefix to prepend to the output files to prevent potential collisions
    45  with other App `StreamingService` output files.
    46  
    47  The `ServiceConstructor` accepts `AppOptions`, the store keys collected using `streamers.x.keys`, a `BinaryMarshaller` and
    48  returns a `StreamingService` implementation. The `AppOptions` are passed in to provide access to any implementation specific configuration options,
    49  e.g. in the case of the file streaming service the `streamers.file.write_dir` and `streamers.file.prefix`.
    50  
    51  ```go
    52  streamingService, err := constructor(appOpts, exposeStoreKeys, appCodec)
    53  if err != nil {
    54      // handler error
    55  }
    56  ```
    57  
    58  The returned `StreamingService` is loaded into the BaseApp using the BaseApp's `SetStreamingService` method.
    59  The `Stream` method is called on the service to begin the streaming process. Depending on the implementation this process
    60  may be synchronous or asynchronous with the message processing of the state machine.
    61  
    62  ```go
    63  bApp.SetStreamingService(streamingService)
    64  wg := new(sync.WaitGroup)
    65  quitChan := make(chan struct{})
    66  streamingService.Stream(wg, quitChan)
    67  ```