buildgrid.server.server module

buildgrid.server.server.load_tls_server_credentials(server_key: str | None = None, server_cert: str | None = None, client_certs: str | None = None) → ServerCredentials | None

Looks-up and loads TLS server gRPC credentials.

Every private and public keys are expected to be PEM-encoded.

Parameters:

  • server_key (str) – private server key file path.

  • server_cert (str) – public server certificate file path.

  • client_certs (str) – public client certificates file path.

Returns:

The credentials for use for a TLS-encrypted gRPC server channel.

Return type:

ServerCredentials

class buildgrid.server.server.Server(max_workers: int | None = None, monitor: bool = False, mon_endpoint_type: MonitoringOutputType = MonitoringOutputType.STDOUT, mon_endpoint_location: str | None = None, mon_serialisation_format: MonitoringOutputFormat = MonitoringOutputFormat.JSON, mon_metric_prefix: str = '', mon_tag_format: StatsDTagFormat = StatsDTagFormat.NONE, auth_method: AuthMetadataMethod = AuthMetadataMethod.NONE, auth_secret: str | None = None, auth_jwks_url: str | None = None, auth_audience: str | None = None, auth_jwks_fetch_minutes: int | None = None, auth_algorithm: AuthMetadataAlgorithm = AuthMetadataAlgorithm.UNSPECIFIED, auth_acl_config: Dict[str, InstanceAuthorizationConfig] | None = None, enable_server_reflection: bool = True, grpc_compression: Compression = Compression.NoCompression)

Bases: object

Creates a BuildGrid server instance.

The Server class binds together all the gRPC services.

register_instance(instance_name: str, instance: Instance) → None

Register an instance with the server. Handled the logic of mapping instances to the correct servicer container.

Parameters:

  • instance_name (str) – The name of the instance.

  • instance (Instance) – The instance implementation.

add_port(address: str, credentials: ChannelCredentials) → None

Adds a port to the server.

Must be called before the server starts. If a credentials object exists, it will make a secure port.

Parameters:

  • address (str) – The address with port number.

  • credentials (grpc.ChannelCredentials) – Credentials object.

property is_instrumented: bool
start(*, on_server_start_cb: OnServerStartCallback | None = None, port_assigned_callback: PortAssignedCallback | None = None, run_forever: bool = True) → None

Starts the BuildGrid server.

BuildGrid server startup consists of 3 stages,

  1. Starting logging and monitoring

This step starts up the logging coroutine, the periodic status metrics coroutine, and the monitoring bus’ publishing subprocess. Since this step involves forking, anything not fork-safe needs to be done after this step.

  1. Instantiate gRPC

This step instantiates the gRPC server, and tells all the instances which have been attached to the server to instantiate their gRPC objects. It is also responsible for creating the various service objects and connecting them to the server and the instances.

After this step, gRPC core is running and its no longer safe to fork the process.

  1. Start instances

Several of BuildGrid’s services use background threads that need to be explicitly started when BuildGrid starts up. Rather than doing this at configuration parsing time, this step provides a hook for services to start up in a more organised fashion.

  1. Start the gRPC server

The final step is starting up the gRPC server. The callback passed in via on_server_start_cb is executed in this step once the server has started. After this point BuildGrid is ready to serve requests.

The final thing done by this method is adding a SIGTERM handler which calls the Server.stop method to the event loop, and then that loop is started up using run_forever().

Parameters:

  • on_server_start_cb (Callable) – Callback function to execute once the gRPC server has started up.

  • port_assigned_callback (Callable) – Callback function to execute once the gRPC server has started up. The mapping of addresses to ports is passed to this callback.

stop(stop_loop: bool = True) → None

Stops the BuildGrid server.