Update archival development guide for visibility archiver (cadence-wo…

…rkflow#2824)

common/archiver/README.md

@@ -28,7 +28,8 @@ type HistoryArchiver interface {
 	// the resource that histories should be archived into. The implementor gets to determine how to interpret the URI.
 	// The Archive method may or may not be automatically retried by the caller. The ArchiveOptions are used
 	// to interact with these retries including giving the implementor the ability to cancel retries and record progress
-	// between retry attempts. 
+  // between retry attempts. 
+  // This method will be invoked after a workflow passes its retention period.
     Archive(context.Context, URI, *ArchiveHistoryRequest, ...ArchiveOption) error
 
     // Get is used to access an archived history. When context expires method should stop trying to fetch history.
@@ -45,13 +46,24 @@ type HistoryArchiver interface {
 
 ```go
 type VisibilityArchiver interface {
+    // Archive is used to archive one workflow visibility record. 
+    // Check the Archive() method of the HistoryArchiver interface in Step 2 for parameters' meaning and requirements. 
+    // The only difference is that the ArchiveOption parameter won't include an option for recording process. 
+    // Please make sure your implementation is lossless. If any in-memory batching mechanism is used, then those batched records will be lost during server restarts. 
+    // This method will be invoked when workflow closes. Note that because of conflict resolution, it is possible for a workflow to through the closing process multiple times, which means that this method can be invoked more than once after a workflow closes.
+    Archive(context.Context, URI, *ArchiveVisibilityRequest, ...ArchiveOption) error
+
+    // Query is used to retrieve archived visibility records. 
+    // Check the Get() method of the HistoryArchiver interface in Step 2 for parameters' meaning and requirements.
+    // The request includes a string field called query, which describes what kind of visibility records should be returned. For example, it can be some SQL-like syntax query string. 
+    // Your implementation is responsible for parsing and validating the query, and also returning all visibility records that match the query. 
+    // Currently the maximum context timeout passed into the method is 3 minutes, so it's ok if this method takes a long time to run.
+    Query(context.Context, URI, *QueryVisibilityRequest) (*QueryVisibilityResponse, error)
+
     // ValidateURI is used to define what a valid URI for an implementation is.
     ValidateURI(URI) error
 }
 ```
-VisibilityArchiver is plumbed throughout the codebase but the full visibility feature is not yet implemented.
-This means even once the VisibilityArchiver is implemented archival of visibility events will not occur. 
-Despite this implementors are still expected to implement this one method interface.
 
 **Step 4: Update provider to provide access to your implementation**
 
@@ -113,7 +125,7 @@ func (a *Archiver) Archive(
 }
 ```
 
-**How does my archiver implementation read history?**
+**How does my history archiver implementation read history?**
 
 The `archiver` package provides a utility class called `HistoryIterator` which is a wrapper of `HistoryManager`. 
 Its usage is simpler than the `HistoryManager` given in the `BootstrapContainer`, 
@@ -124,4 +136,8 @@ Sample usage can be found in the filestore historyArchiver implementation.
 **Should my archiver define all its own error types?**
 
 Each archiver is free to define and return any errors it wants. However many common errors which
-exist between archivers are already defined in `constants.go`.
+exist between archivers are already defined in `constants.go`.
+
+**Is there a generic query syntax for visibility archiver?**
+
+Currently no. But this is something we plan to do in the future. As for now, try to make your syntax similar to the one used by our advanced list workflow API.