LaunchConfig

class gpype.common.launch_config.LaunchConfig

Bases: object

Global launch configuration singleton.

Stores startup parameters for the entire application. All Source/Sink nodes and other components read from this global configuration.

Supports three ways to configure: 1. Direct assignment: LaunchConfig.configure(residency=…, …) 2. Command-line parsing: LaunchConfig.parse_args(sys.argv[1:]) 3. Programmatic: LaunchConfig.get() then modify fields

Usage in main():

def main():
    LaunchConfig.parse_args()
    # ... rest of application

Usage in nodes:

config = LaunchConfig.get()
if config.is_edge():
    ...

residency = 'standalone'

standalone, edge, or server

Type:

Residency mode

edge_id = None

Which edge this process is, under EDGE residency. A node that names an edge is built only by the edge of that name; a node that names none is built by every edge. None – the only value a server or a standalone process has – means “no edge”, never “every edge”, so an edge launched without one builds only the nodes that name none.

endpoint = None

WebSocket endpoint URL for edge/server communication. A wss scheme is what switches the data socket to TLS: both ends read the same endpoint, so they cannot disagree about whether the socket between them is encrypted.

bind = 'any'

Which interfaces a SERVER’s broker binds. Not derivable from endpoint: that host is what an edge dials, and a container advertises an address it does not bind. Inert in the other two residencies, which bind nothing.

certfile = None

PEM certificate the SERVER’s broker presents. Required for a wss endpoint in server residency.

keyfile = None

PEM private key, if it is not inside certfile.

ca_file = None

A certificate an EDGE should trust in addition to the system store. How a self-signed deployment is verified rather than waved through.

allow_insecure = False

Cross a network in the clear, or skip verifying a certificate. A named choice, because the samples on this socket are the recording and the alternative is silence about it.

data_token = None

The token this process presents when it dials a broker, i.e. what an EDGE sends. None means present nothing, which a broker accepts only if it requires nothing.

data_tokens = None

The tokens this process accepts when it serves a broker, keyed by capability – {"put": ..., "subscribe": ...}. None means accept every connection, which is what a STANDALONE or LAN run has always done; a deployment sets it and the broker then refuses anything unauthenticated.

Two capabilities rather than one, because the fan-in direction is a single receiver slot, held by whichever connection writes it first: a connection that may PUT can take the stream an amplifier is meant to feed. Read access and write access are therefore different grants, and a viewer gets only the first.

save_as = None

Record every source’s frames, at the point right after its core and before any Link, Oscar or Sync. A path stem: the run is a directory of one file per stream plus a manifest, because there is one recording per source and they only mean anything together.

Here rather than on the nodes, and for the same reason residency is: it is a property of how this process was launched, not of the pipeline. One consequence is worth knowing – it is read while the chains are built, so it must be set before the first source is constructed. A command line satisfies that by itself, since LaunchConfig parses argv on first access.

load_from = None

Replay a run recorded by save_as, in place of every source’s own core. The run directory, or its manifest.

classmethod get()

Get the singleton instance, creating if needed.

On first call, parses sys.argv unless configure() was already called programmatically.

Return type:

LaunchConfig

Returns:

The global LaunchConfig instance.

classmethod configure(residency='standalone', endpoint=None, bind='any', certfile=None, keyfile=None, ca_file=None, allow_insecure=False, data_token=None, data_tokens=None, save_as=None, load_from=None, edge_id=None)

Configure the global launch settings.

Parameters:

• residency (str) – One of Constants.Residency values.

• endpoint (Optional[str]) – WebSocket server URL (required for edge/server). A wss scheme switches the data socket to TLS.

• bind (str) – Which interfaces a server-residency broker listens on, one of Constants.Bind values. Separate from endpoint because that host is the one clients dial.

• certfile (Optional[Path]) – PEM certificate for a server-residency broker.

• keyfile (Optional[Path]) – PEM private key, if not inside certfile.

• ca_file (Optional[Path]) – A certificate an edge should trust.

• allow_insecure (bool) – Permit a plaintext socket to a host that is not this machine.

• data_token (Optional[str]) – What an EDGE presents to the broker it dials. Falls back to GPYPE_DATA_TOKEN in the environment, which is how a process launched by an operator receives one – deliberately not a command-line flag, because argv is visible in a process list.

• data_tokens (Optional[dict]) – What a SERVER’s broker accepts, keyed by capability (put, subscribe). None keeps the historical behaviour of accepting every connection.

• save_as (Optional[str]) – Record every source’s raw frames under this path stem. See save_as.

• load_from (Optional[str]) – Replay a recorded run instead of building any source’s own core. See load_from.

• edge_id (Optional[str]) – Which edge this process is. EDGE residency only; falls back to GPYPE_EDGE_ID in the environment. See edge_id.

Return type:

LaunchConfig

Returns:

The configured LaunchConfig instance.

Raises:

• ValueError – If residency is invalid or required params missing, if both save_as and load_from are given, or if an edge_id is given outside EDGE residency or is not a usable name.

• TypeError – If edge_id is not a string.

• InsecureTransportError – If the endpoint is plaintext and names a host reachable from a network, and that was not asked for. The samples on this socket are the recording, so crossing a network in clear is a choice to be made rather than a default to fall into.

server_tls()

The certificate this process’s broker should present, if any.

Return type:

Optional[ServerTls]

Returns:

A ServerTls when the endpoint asks for TLS, else None.

client_tls()

How this process should verify the broker it connects to.

Return type:

Optional[ClientTls]

Returns:

A ClientTls when the endpoint asks for TLS, else None. allow_insecure here means “do not verify”, which is a different thing from “do not encrypt” and is why it is one flag rather than two: a deployment that has said it trusts this network has said the same thing both times.

classmethod parse_args(args=None, parser=None, quiet=False)

Parse command-line arguments into launch configuration.

No-op if LaunchConfig was already configured programmatically (i.e. configure() was called before this).

Parameters:

• args (Optional[Sequence[str]]) – Command-line arguments. Defaults to sys.argv[1:].

• parser (Optional[ArgumentParser]) – Custom ArgumentParser to extend. If None, creates a new parser with standard g.Pype arguments.

• quiet (bool) – Do not print usage and an error message when the argv cannot be parsed. Used by the implicit path in get_instance(), where the failure is caught and defaults are applied anyway, so the message describes nothing the caller can act on. Ignored when parser is supplied, since that parser belongs to the caller.

Return type:

LaunchConfig

Returns:

The configured LaunchConfig instance.

Example

# In main() config = LaunchConfig.parse_args()

bind_hosts()

The host argument a broker should bind for this config.

Returns:

None for Constants.Bind.ANY, which asyncio binds as the wildcard on every interface and both address families; otherwise the loopback addresses this host has, as literals.

Raises:

ValueError – If bind is not a Constants.Bind value. Read access validates too, because the class documents assignment as a supported route – and the failure this prevents is silent: any unrecognised value would otherwise fall through to the loopback branch, and a deployment that typed "ANY" would bind loopback and see every edge refused with nothing logged.

The loopback case names 127.0.0.1 and ::1 rather than localhost on purpose. Binding the name would resolve it, and the resolution order is what cost every client ~2.0 s on a refused IPv6 attempt before this bind covered both families (measured: 2.021 s, against 0.002 s). Naming both literals keeps that property while refusing everything off this machine.

classmethod reset()

Reset to default configuration.

Clears the raw-recording state too, so that reset() and configure() are symmetric. They were not: only configure cleared the stream-key ordinals, the run directory and the replay anchor, so a host taking the documented third route – get() and then assign the fields – kept the previous run’s ordinals, and a pipeline would ask for Generator_1 from a run that had recorded Generator_0. That is exactly the drift the reset in configure exists to prevent.

Return type:

None

property link_config

Get link configuration dict for Source/Sink nodes.

Returns:

Dict with endpoint, or None for standalone.

is_standalone()

Check if running in standalone mode.

Return type:

bool

is_edge()

Check if running in edge mode.

Return type:

bool

is_server()

Check if running in server mode.

Return type:

bool

__init__(residency='standalone', edge_id=None, endpoint=None, bind='any', certfile=None, keyfile=None, ca_file=None, allow_insecure=False, data_token=None, data_tokens=None, save_as=None, load_from=None, _instance=None)