a11::service::Service Class Reference

A registry of actions, the sessions serving them, and their lifecycle. More...

#include <cpp/a11/service/service.h>

Inheritance diagram for a11::service::Service:

Classes
struct	State

Public Member Functions
	~Service ()
	Service (const Service &)=delete
Service &	operator= (const Service &)=delete
std::shared_ptr< actions::ActionRegistry >	GetActionRegistry () const
absl::Status	SetActionRegistry (const std::shared_ptr< actions::ActionRegistry > &action_registry)
	Replace the registry new connections are built from.
absl::Status	SetOnConnection (OnServiceConnection on_connection)
	Replace the per-connection hook.
absl::StatusOr< std::string >	Describe (std::string_view name, std::string_view query) const
	Describes this service's actions, for GET /actions.
net::DescribeActionsHandler	DescribeHandler ()
	A net::DescribeActionsHandler bound to this service.
a11::Task	Serve (std::shared_ptr< net::WireStream > stream, StreamMode mode=StreamMode::kAccept)
	Serve one stream, resolving when its session is finished.
absl::StatusOr< std::shared_ptr< Session > >	StartStreamHandler (const std::shared_ptr< net::WireStream > &stream, StreamMode mode=StreamMode::kAccept)
	Start serving one stream and return its session immediately.
absl::Status	AddStreamToSession (std::string_view session_id, const std::shared_ptr< net::WireStream > &stream, StreamMode mode=StreamMode::kAccept)
	Attach another transport to an existing session.
std::vector< std::string >	SessionIds () const
absl::StatusOr< std::shared_ptr< Session > >	GetSession (std::string_view session_id) const
absl::StatusOr< std::shared_ptr< Session > >	GetSessionForStream (std::string_view stream_id) const
size_t	SessionCount () const
bool	accepting () const
absl::Status	StopAccepting ()
	Refuse new connections, leaving live ones alone.
a11::Task	Drain (absl::Duration timeout=absl::InfiniteDuration())
	Wait for live sessions to finish.
absl::Status	Abort (const absl::Status &status)
	Stop accepting and abort every live session with status.
a11::Task	Done () const

Static Public Member Functions
static absl::StatusOr< std::shared_ptr< Service > >	Create (std::shared_ptr< actions::ActionRegistry > action_registry=nullptr, OnServiceConnection on_connection={}, ServiceOptions options={})
	Create a service.

Detailed Description

A registry of actions, the sessions serving them, and their lifecycle.

Thread-safe. Sessions are tracked from the moment they are created until they finish, so a service can be drained: it stops accepting, waits for what is in flight, and only then lets go.

Constructor & Destructor Documentation

~Service()

a11::service::Service::~Service

(

)

Service()

a11::service::Service::Service ( const Service &  )

delete

Member Function Documentation

Abort()

absl::Status a11::service::Service::Abort

(

const absl::Status &

status

)

Stop accepting and abort every live session with status.

accepting()

bool a11::service::Service::accepting

(

)

const

Returns

Whether new connections are still admitted.

AddStreamToSession()

absl::Status a11::service::Service::AddStreamToSession	(	std::string_view	session_id,
		const std::shared_ptr< net::WireStream > &	stream,
		StreamMode	mode = StreamMode::kAccept
	)

Attach another transport to an existing session.

Create()

absl::StatusOr< std::shared_ptr< Service > > a11::service::Service::Create ( std::shared_ptr< actions::ActionRegistry >  action_registry = nullptr, OnServiceConnection  on_connection = {}, ServiceOptions  options = {}  )

static

Create a service.

Parameters

action_registry	Registry incoming calls resolve against; an empty one is created when null.
on_connection	Optional per-connection hook; see OnServiceConnection.
options	Session limits, registry-copy policy, drain timeout.

Returns

The service, or InvalidArgument when options are inconsistent.

Describe()

absl::StatusOr< std::string > a11::service::Service::Describe	(	std::string_view	name,
		std::string_view	query
	)		const

Describes this service's actions, for GET /actions.

Uses the same describer as __list_actions__, keeping the endpoint and action responses consistent. Transports do not maintain a separate registry.

Parameters

name	One action to describe, or empty for the whole collection.
query	URL query string, without the ?, carrying the filters.

Returns

The a11.actions/v1 document, or NotFound for an unknown name.

DescribeHandler()

net::DescribeActionsHandler a11::service::Service::DescribeHandler

(

)

A net::DescribeActionsHandler bound to this service.

Holds a weak reference, so installing it on a listener does not keep the service alive past its own shutdown.

Done()

a11::Task a11::service::Service::Done

(

)

const

Returns

A Task resolving once the service is closed and empty.

Drain()

a11::Task a11::service::Service::Drain

(

absl::Duration

timeout = absl::InfiniteDuration()

)

Wait for live sessions to finish.

Parameters

timeout

How long to wait; sessions still running after it are left alone (use Abort to end them).

Returns

A Task resolving when no sessions remain, or DeadlineExceeded.

GetActionRegistry()

std::shared_ptr< actions::ActionRegistry > a11::service::Service::GetActionRegistry

(

)

const

Returns

The template registry new connections are built from.

GetSession()

absl::StatusOr< std::shared_ptr< Session > > a11::service::Service::GetSession

(

std::string_view

session_id

)

const

Returns

The session with this id, or NotFound.

GetSessionForStream()

absl::StatusOr< std::shared_ptr< Session > > a11::service::Service::GetSessionForStream

(

std::string_view

stream_id

)

const

Returns

The session serving this stream, or NotFound.

operator=()

Service & a11::service::Service::operator= ( const Service &  )

delete

Serve()

a11::Task a11::service::Service::Serve	(	std::shared_ptr< net::WireStream >	stream,
		StreamMode	mode = StreamMode::kAccept
	)

Serve one stream, resolving when its session is finished.

The shape a transport's on-stream callback wants: hold the connection open for as long as it lasts. Rejects with FailedPrecondition once the service has stopped accepting.

SessionCount()

size_t a11::service::Service::SessionCount

(

)

const

Returns

How many sessions are currently being served.

SessionIds()

std::vector< std::string > a11::service::Service::SessionIds

(

)

const

Returns

The ids of the sessions currently being served.

SetActionRegistry()

absl::Status a11::service::Service::SetActionRegistry

(

const std::shared_ptr< actions::ActionRegistry > &

action_registry

)

Replace the registry new connections are built from.

No stream is interrupted, and any action message arriving after this call resolves against the new registry. Live sessions keep the registry they have when ServiceOptions::copy_registry_per_connection is set – their per-peer additions must not be clobbered – and are re-pointed when it is not. This is what makes prototyping against a running service possible.

SetOnConnection()

absl::Status a11::service::Service::SetOnConnection

(

OnServiceConnection

on_connection

)

Replace the per-connection hook.

Affects connections from now on.

StartStreamHandler()

absl::StatusOr< std::shared_ptr< Session > > a11::service::Service::StartStreamHandler	(	const std::shared_ptr< net::WireStream > &	stream,
		StreamMode	mode = StreamMode::kAccept
	)

Start serving one stream and return its session immediately.

For a caller that wants the handle – to add a second transport to the same peer, or to inspect it – and is content for the service to own completion.

StopAccepting()

absl::Status a11::service::Service::StopAccepting

(

)

Refuse new connections, leaving live ones alone.

The first half of a graceful shutdown: stop accepting, then Drain.

---

The documentation for this class was generated from the following files:

• cpp/a11/service/service.h
• cpp/a11/service/service.cc