An App that is used as a server in at least one client-server IPC split. More...

#include <app.hpp>

Inheritance diagram for ipc::session::Server_app:

Collaboration diagram for ipc::session::Server_app:

Public Types
using	Master_set = boost::unordered_map< std::string, Server_app >
	Suggested type for storing master repository or all `Server_apps`s. See App doc header for discussion.

using	Client_app_set = boost::unordered_set< std::string >
	Short-hand for existence-checkable set of `Client_app`s via App::m_name.

Public Types inherited from ipc::session::App
using	Master_set = boost::unordered_map< std::string, App >
	Suggested type for storing master repository or all `Apps`s. See App doc header for discussion.

Public Attributes
Client_app_set	m_allowed_client_apps
	A given Client_app (as identified by its distinct App::m_name) may request to establish an IPC session with an instance of `*this` Server_app as the conversation partner process if and only if it is in this set.

fs::path	m_kernel_persistent_run_dir_override
	Absolute path to the directory (without trailing separator) in the file system where kernel-persistent runtime, but not temporary, information shall be placed for this particular application; leave empty to use the default system path instead. More...

util::Permissions_level	m_permissions_level_for_client_apps
	Specifies level of access for `Client_app`s (which must, also, be in m_allowed_client_apps at any rate) as enforced by file system permissions. More...

Public Attributes inherited from ipc::session::App
std::string	m_name
	Brief application name, readable to humans and unique across all other applications' names; used both as a short programmatic key in shared resource naming (including as a folder in Shared_name for kernel-persistent resources and addresses; and in path names – such as PID file name – in the file system). More...

fs::path	m_exec_path
	Absolute, lexically normalized canonical path to the executable entity (which is not a directory), as it would appear in a command line or `exec()`-like invocation when actually invoking the application. More...

util::user_id_t	m_user_id
	The application must run as this user ID (UID). Files and other shared resources shall have this owner.

util::group_id_t	m_group_id
	The application must run as this group ID (GID). Files and other shared resources shall have this owner.

Related Functions
(Note that these are not member functions.)
std::ostream &	operator<< (std::ostream &os, const Server_app &val)
	Prints string representation of the given `Server_app` to the given `ostream`. More...

Related Functions inherited from ipc::session::App
std::ostream &	operator<< (std::ostream &os, const App &val)
	Prints string representation of the given `App` to the given `ostream`. More...

Detailed Description

An App that is used as a server in at least one client-server IPC split.

This is explained in the "App, Client_app, Server_app registry conventions" section of the struct App doc header.

See also: struct App doc header.

As explained there, each Server_app – in addition to the source App fields copied from an App in the master App repository – ultimately stores references (by App::m_name) to the Client_apps describing client apps that may initiate sessions with that Server_app.

Friends And Related Function Documentation

◆ operator<<()

std::ostream & operator<<	(	std::ostream &	os,
		const Server_app &	val
	)

Parameters

os	Stream to which to write.
val	Object to serialize.

Returns: os.

Member Data Documentation

◆ m_kernel_persistent_run_dir_override

fs::path ipc::session::Server_app::m_kernel_persistent_run_dir_override

Absolute path to the directory (without trailing separator) in the file system where kernel-persistent runtime, but not temporary, information shall be placed for this particular application; leave empty to use the default system path instead.

Informally: In production it is recommended to leave this empty, as the default system path is a well known location (namely /var/run) where one would expect to find such files.

Kernel-persistent means that it'll disappear at reboot; runtime, but not temporary, means it's... not a thing that might be wiped spuriously anytime (informally: not /tmp). Informally: just know that it is normally /var/run, and that it stores things such as process-ID (PID) files.

It shall be a Unix path and absolute (starts with forward-slash) (and lacks a root-name). Informally it is probably best for it to be lexically normal as well.

Rationale

Why allow this override, if the default is sensible? Answer: The default usually requires admin privileges for writing. For test/debug purposes a location like /tmp or /tmp/var/run can be convenient.

◆ m_permissions_level_for_client_apps

util::Permissions_level ipc::session::Server_app::m_permissions_level_for_client_apps

Specifies level of access for Client_apps (which must, also, be in m_allowed_client_apps at any rate) as enforced by file system permissions.

Specifically, as of this writing, it determines at least the following items. Note that ownership is identified by the UID/GID settings (matching *this App::m_user_id and App::m_group_id) of various files and other shared resources created by the server* application in the ipc::session framework. (* - Actually, at times, resources are created by the client application too. See below.)

File permissions set on the CNS (PID) file established by Session_server. A given Client_session (etc.) must read this file in order to know to which Session_server to issue a session-open request (establish a Session); if it cannot access that file, it cannot open a session against this Server_app.
- If this check fails, and everything is functioning as generally intended internally, then the below items are moot (as opening a session is a prerequisite for anything else).
Permissions set on any SHM pool created for a given "shm::*::Server_session". and "shm::*::Session_server". A Client_app may not be able to complete its session-open attempt (shm::classic::Client_session::sync_connect(), etc.) if its user lacks the permissions to open the underlying SHM-pool(s) resource in the file system.(It also conceivably may be able to complete the session-open but fail if opening a pool on-demand later; the session will then likely end prematurely. This depends on the inner workings of the particular SHM system chosen; shm::classic::Client_session opens pools during session-open procedure exclusively, but other systems may behave differently.)
- Arena-lending SHM providers – as of this writing namely ipc::shm::arena_lend::jemalloc – involve both sides (session-server and session-client) each creating SHM pool(s) for allocations from within their respective processes. m_permissions_level_for_client_apps applies to the server-created pools, yes; but also client-created pools. At the moment it seems to me (ygoldfel) that nevertheless a common setting in Server_app still makes sense. In practice, it means this: If this is set to util::Permissions_level::S_USER_ACCESS, then the Client_app and Server_app UID/GID shall need to be equal; if util::Permissions_level::S_GROUP_ACCESS then just the GID (while UIDs ideally would be different).(Obviously if S_UNRESTRICTED then does not matter.) Don't see the sense in making this a separate knob in Client_app. Maybe though? Not a formal to-do for now.
Similarly (to preceding bullet point, minus the arena_lend caveat) for bipc MQs. ipc::session opens such MQs (if so configured at compile-time) during session-open; hence on permissions failure the session-open will itself fail.
Similarly (to preceding bullet point) for POSIX MQs.

As of this writing the list is complete; however it is conceivable it may be analogously extended to more resources.

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

session/app.hpp
session/session_fwd.hpp

Public Types

Public Attributes