Status: Work In Progress. Discussion and comments in Issue 3246.

Table of Contents:

1. Motivation
2. Requirements
3. Design
4. API Changes
5. Limitations
6. Server-Side Changes

Enable a way to add Tags to a given Stream. Tags are singleton labels that are useful specify identifying attributes of a Pravega Stream that are meaningful and relevant to users. These singleton tags do not directly imply semantics to the core Pravega system. Tags can be used to organize and select a subset of Streams under a given Scope.

This will enable the ability to tag streams with the type of content indicating whether the stream contains video, JSON, or something else for the given Scope.

Example labels:

• contentType=video
• camera=NorthWing-1
• location=pillarB3
• sensor_12_3

The requirements for this feature are listed below.

• A valid Tag or singleton label can be up to 256 Unicode characters in length.
• A Stream can be associated with up to 128 Tags.
• A valid Tag or singleton label must begin with an alphanumeric character ([a-z0-9A-Z])
• A valid tag contains dashes (-), equals(=), underscores (_), dots (.), and alphanumeric between.

• Same pattern as followed by other Controller APIs
  • READ permissions for all the get APIs.
  • READ_UPDATE permissions for all the update/create APIs.

At a high level, the controller will use the workflow of UpdateStream to manage the tag and inverted index operation on the controller. (TODO: The details of this approach are being flushed out.)

The below GRPC APIs on the controller will be modified or added. The client(both JAVA and RUST client) will use these APIs to implement the Stream Tag-related functionality. The user will be allowed to pass labels along with the StreamConfiguration while creating and updating a Stream. This implies io.pravega.client.stream.StreamConfiguration` class will now contain a new attribute that represents a Set of Labels.

a. CREATE STREAM The user can pass the labels to be associated with a Pravega Stream along with the Stream Configuration. The GRPC API will follow the below pattern. (No changes from the previous API here.)

CompletableFuture<Boolean> createStream(final String scope, final String streamName, 
                                                            final StreamConfiguration streamConfig);

b. UPDATE STREAM The user will be able to update the labels along with the Stream Configuration using the updateStream API. The GRPC API will follow the below pattern. ( No changes from the previous controller API here.)

CompletableFuture<Boolean> updateStream(final String scope, final String streamName, 
                                                            final StreamConfiguration streamConfig);

c. GET TAGS Get tags API is a new GRPC API that will enable users to fetch the current tags for a given Scope and Stream.

CompletableFuture<Set<String>> getTags(final String scope, final String streamName);

d. LIST STREAMs with a given tag(s). The below GRPC API will be added that will enable users to fetch Streams under a given Scope that matches the provided tags.

/**
 * List Streams under a scope which the matching tags. 
 * A continuation token will be used by GRPC server to paginate the results.
 */
public AsyncIterator<Stream> listStream(String scopeName, String... tags)

The below already existing REST APIs on the controller will be updated to handle tags.

• /scopes/{scopeName}/streams
• /scopes/{scopeName}/streams/{streamName}

• The update tag APIs are strongly consistent given that it is treated similarly to an update stream operation.
• In case of a concurrent read and update operation the read APIs will show the current state of the tags and once the future for the update operation completes the newer state will be returned.

• No changes expected here. The controller will interact with the TableSegments to store the Tag metadata and the reverse index.

• TODO.