github.com/lirm/aeron-go@v0.0.0-20230415210743-920325491dc4/archive/README.md (about)

     1  # aeron-go/archive
     2  
     3  Implementation of [Aeron Archive](https://github.com/real-logic/Aeron/tree/master/aeron-archive) client in Go.
     4  
     5  The [Aeron Archive
     6  protocol](http://github.com/real-logic/aeron/blob/master/aeron-archive/src/main/resources/archive/aeron-archive-codecs.xml)
     7  is specified in xml using the [Simple Binary Encoding (SBE)](https://github.com/real-logic/simple-binary-encoding)
     8  
     9  ## Current State
    10  The implementation is the second beta release. The API may still be changed for bug fixes or significant issues.
    11  
    12  # Design
    13  
    14  ## Guidelines
    15  
    16  The structure of the archive client library is heavily based on the
    17  Java archive library. It's hoped this will aid comprehension, bug fixing,
    18  feature additions etc.
    19  
    20  Many design choices are also based upon the golang client library as
    21  the archive library is a layering on top of that.
    22  
    23  Finally golang idioms are used where reasonable.
    24  
    25  The archive library does not lock and concurrent calls on an archive
    26  client to invoke the aeron-archive protocol calls should be externally
    27  locked to ensure only one concurrent access.
    28  
    29  ### Naming and other choices
    30  
    31  Function names used in archive.go which contains the main API are
    32  based on the Java names so that developers can more easily switch
    33  between languages and so that any API documentation is more useful
    34  across implementations. Some differences exist due to capitalization
    35  requirements, lack of polymorphism, etc.
    36  
    37  Function names used in encoders.go and proxy.go are based on the
    38  protocol specification. Where the protocol specifies a type that can
    39  be naturally represented in golang, the golang type is used used where
    40  possible until encoding. Examples include the use of `bool` rather than
    41  `BooleanType` and `string` over `[]uint8`
    42  
    43  ## Structure
    44  
    45  The archive protocol is largely an RPC mechanism built on top of
    46  Aeron. Each Archive instance has it's own aeron instance running a
    47  [proxy](proxy.go) (publication/request) and [control](control.go) (subscription/response)
    48  pair. This mirrors the Java implementation. The proxy invokes the
    49  encoders to marshal packets using SBE.
    50  
    51  Additionally there are some asynchronous events that can arrive on a
    52  [recordingevents](recordingevents.go) subscription. These
    53  are not enabled by default to avoid using resources when not required.
    54  
    55  ## Synchronous unlocked API optionally using polling
    56  
    57  The implementation provides a synchronous API as the underlying
    58  mechanism is largely an RPC mechanism and archive operations are not
    59  considered high frequency.
    60  
    61  If needed it is simple in golang to wrap a synchronous API with a
    62  channel (see for example aeron.AddSubscription().
    63  
    64  Some asynchronous events do exist (e.g, recording events and
    65  heartbeats) and to be delivered the polling mechanisms of
    66  RecordingEventsPoll() and PollForErrorResponse() are provided. These
    67  may be easily wrapped in a goroutine if desired,
    68  
    69  ## Examples
    70  
    71  Examples are provided for a [basic_recording_publisher](examples/basic_recording_publisher/basic_recording_publisher.go) and [basic_replayed_subscriber](examples/basic_replayed_subscriber/basic_replayed_subscriber.go) that interoperate with the Java examples.
    72  
    73  ## Security
    74  
    75  Enabling security is done via setting the various auth options. [config_test.go](config_test.go) and [archive_test.go](archive_test.go) provide an example.
    76  
    77  The actual semantics of the security are dependent upon which authenticator supplier you use and is tested against [secure-logging-archiving-media-driver](secure-logging-archiving-media-driver).
    78  
    79  # Backlog
    80   * godoc improvements
    81   * more testing
    82    * archive-media-driver mocking/execution
    83    * test cleanup in the media driver can be problematic
    84   * Auth should provide some callout mechanism
    85   * various FIXMEs
    86   * There seems to be problems if there are multiple archive
    87     instances. Particularly noticeable when calling aeron.Close()
    88  
    89  # Bigger picture issues
    90   * Java and C++ poll the counters to determine when a recording has actually started but the counters are not
    91     available in go. As a result we use delays and 'hope' which isn't ideal.
    92   * It would be nice to silence the OnAvailableCounter noise
    93   * Within aeron-go there are cases of Log.Fatalf(), see for example trying to add a publication on a "bogus" channel.
    94  
    95  ## Release Notes
    96  
    97  ### 1.0b3 (in-progress)
    98   * Add PollForErrorResponse()
    99   * concurrency improvements by having the library lock around RPCs
   100  
   101  ### 1.0b2
   102   * Handle different archive clients using same channel/stream pairing
   103   * Provide Subscription.IsConnected() and IsRecordingEventsConnected()
   104   * Replace go-logging with zap to avoid reentrancy crashes in logging library
   105   * Improve the logging by downgrading in severity and message tone some warning level messages
   106   * Fix a race condition looking up correlationIDs on ControlResponse
   107   * Fix a return code error in StopRecordingById()
   108   * Fix unused argumentin StopRecording()
   109   * Cosmetic improvements for golint and staticcheck
   110   * Make the Listeners used for async events be per archive client instead of global
   111