buildgrid.server.build_events.storage module

exception buildgrid.server.build_events.storage.DuplicateStreamError

Bases: Exception

Error when encountering a name collision between event streams.

class buildgrid.server.build_events.storage.BuildEventStream(stream_id: StreamId)

Bases: object

Internal representation of a stream of OrderedBuildEvents.

This class provides in-memory storage of the events in a given Build Event Stream. Many of these Build Event Streams may relate to the same build, or even to the same invocation of a tool.

Parameters:

stream_id (StreamId) – A gRPC message defining the ID of this stream.

publish_event(event: OrderedBuildEvent) → None

Publish an OrderedBuildEvent into the stream.

Parameters:

event (OrderedBuildEvent) – The event to publish to the stream. This is an OrderedBuildEvent message from the publish_build_event proto.

query_events(query: str | None = None) → Iterator[OrderedBuildEvent]

Query the contents of this stream.

Filter the contents of the event stream by some query, returning an iterator of matching OrderedBuildEvents.

Note

The filtering functionality of this method is currently not implemented, and the iterator returned contains all the events in the stream no matter what query is used.

Parameters:

query (str) – The filter string to use when querying events.

to_grpc_message() → BuildEventStream

Convert this object to a BuildEventStream gRPC message.

This method converts this internal event stream representation into a QueryEventStreamsResponse.BuildEventStream gRPC message, as defined in the query_build_events proto.

class buildgrid.server.build_events.storage.BuildEventStreamStorage

Bases: Instance

In-memory storage of Build Event Streams.

This class stores a collection of Build Event Streams, and handles both creation of new streams and querying the streams which already exist based on their stream ID. Streams are stored in-memory and are lost on service restart, so shouldn’t be relied on as a source of persistent data when using this storage class.

This class is similar to the .*Instance classes used by other BuildGrid services, in that it is instantiated by the config parser and used by a .*Service class instantiated by the server class. Unlike the other instance classes however, this class doesn’t have an instance_name attribute due to the Build Events protos not having the concept of multiple instances.

SERVICE_NAME: ClassVar[str] = 'BuildEvents'

The expected FULL_NAME of the Service which will wrap this instance. This value should be declared on the class of any Instance implementations.

new_stream(stream_id: StreamId) → BuildEventStream

Create and return a new BuildEventStream with the given ID.

This method creates a new BuildEventStream with the given StreamId, and returns it. If a stream with that ID already exists in this BuildEventStreamStorage, then a DuplicateStreamError is raised.

Parameters:

stream_id (StreamId) – The gRPC StreamId message containing the ID of the stream to create.

get_stream(stream_id: StreamId) → BuildEventStream

Return a BuildEventStream with the given stream ID.

This method takes a stream ID, converts it to a stream key, and returns the stream with that key if one exists.

This method will create a new BuildEventStream if one with the given ID doesn’t exist.

Parameters:

stream_id (StreamId) – The StreamID message from an event to get the BuildEventStream for.

Returns:

A BuildEventStream with the given ID, or None.

get_matching_streams(stream_key_regex: str) → list[BuildEventStream]

Return a list of event streams which match the given key pattern.

This method takes a regular expression as a string, and returns a list of BuildEventStream objects whose stream key (based on the events’ StreamId) matches the regex.

Parameters:

stream_key_regex (str) – A regular expression to use to find matching streams.

Returns:

List of BuildEventStream objects which have a key matching the given regex.