pip_services3_components.connect package

Submodules

Module contents

pip_services3_components.connect.__init__

Contains implementation of connection parameters, using various connection strings, which are stripped of all credentials. If we need to configure a service, the port, ip address, protocol, and other parameters – we use the ConnectionParams object, and relevant helper classes (like ConnectionResolver), for acquiring these parameters, and for discovery of objects, components (which store and retrieve connection parameters).

### Discovery ###

Service that store a registry of various end-points (what services are where, and how to connect to them). It knows the end-points, but doesn’t have the credentials to connect to them. Separated for security reasons. IDiscovery – interface for creating registries. MemoryDiscovery – registry that is stored in memory.

There exist 2 types of discovery:

  • Static discovery: all services have static IP addresses (like DNS, which also works using static

discovery) that are configured from the start and don’t change along the way. As of lately, used more often than dynamic, because it is simpler to use and more reliable. - Proxy (or reverse proxy) is created with a dns name, and all the dynamics of starting/restarting/switching from one host to another – everything is nice and clear for the clients. Infrastructure does all the hard work out of the box. - Configure sets the static registry. - Dynamic discovery: every time a service starts, it registers its address in the discovery service (“Service name” at the following address “IP”). Clients then ask to resolve the address by which the requested service can be reached. The service has a general name, by which other services can resolve it. - If a service stops working, you need to refresh its address, clean stale addresses, heartbeats must be used – lots of problems and challenges. One service can have more than one address.

copyright

Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.

license

MIT, see LICENSE for more details.

class pip_services3_components.connect.CompositeConnectionResolver

Bases: pip_services3_commons.refer.IReferenceable.IReferenceable, pip_services3_commons.config.IConfigurable.IConfigurable

Helper class that resolves connection and credential parameters, validates them and generates connection options.

### Configuration parameters ###
  • connection(s):

    • discovery_key: (optional) a key to retrieve the connection from IDiscovery

    • protocol: communication protocol

    • host: host name or IP address

    • port: port number

    • uri: resource URI or connection string with all parameters in it

  • credential(s):

    • store_key: (optional) a key to retrieve the credentials from ICredentialStore

    • username: user name

    • password: user password

### References ###

  • *:discovery:*:*:1.0 (optional) IDiscovery services to resolve connections

  • *:credential-store:*:*:1.0 (optional) Credential stores to resolve credentials

compose(correlation_id: Optional[str], connections: List[pip_services3_components.connect.ConnectionParams.ConnectionParams], credential: pip_services3_components.auth.CredentialParams.CredentialParams, parameters: pip_services3_commons.config.ConfigParams.ConfigParams) → pip_services3_commons.config.ConfigParams.ConfigParams

Composes Composite connection options from connection and credential parameters.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • connections – connection parameters

  • credential – credential parameters

  • parameters – optional parameters

Returns

resolved options or error.

configure(config: pip_services3_commons.config.ConfigParams.ConfigParams)

Configures component by passing configuration parameters.

Parameters

config – configuration parameters to be set.

resolve(correlation_id: Optional[str]) → pip_services3_commons.config.ConfigParams.ConfigParams

Resolves connection options from connection and credential parameters.

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

Returns

resolved options or error

set_references(references: pip_services3_commons.refer.IReferences.IReferences)

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

class pip_services3_components.connect.ConnectionParams(map: Any = None)

Bases: pip_services3_commons.config.ConfigParams.ConfigParams

Contains connection parameters to connect to external services.

They are used together with credential parameters, but usually stored separately from more protected sensitive values.

### Configuration parameters ###

  • discovery_key: key to retrieve parameters from discovery service

  • protocol: connection protocol like http, https, tcp, udp

  • host: host name or IP address

  • port: port number

  • uri: resource URI or connection string with all parameters in it

In addition to standard parameters ConnectionParams may contain any number of custom parameters

Example:

connection = ConnectionParams.from_tuples("protocol", "http",
                                          "host", "10.1.1.100",
                                          "port", "8080",
                                          "cluster", "mycluster")

host = connection.get_host()                              # Result: "10.1.1.100"
port = connection.get_port()                              # Result: 8080
cluster = connection.get_as_nullable_string("cluster")    # Result: "mycluster"
static from_config(config: pip_services3_commons.config.ConfigParams.ConfigParams) → pip_services3_components.connect.ConnectionParams.ConnectionParams

Retrieves a single ConnectionParams from configuration parameters from “connection” section. If “connections” section is present instead, then is returns only the first connection element.

Parameters

config – ConnectionParams, containing a section named “connection(s)”.

Returns

the generated ConnectionParams object.

static from_string(line: str) → pip_services3_components.connect.ConnectionParams.ConnectionParams

Creates a new ConnectionParams object filled with key-value pairs serialized as a string.

Parameters

line – a string with serialized key-value pairs as “key1=value1;key2=value2;…” Example: “Key1=123;Key2=ABC;Key3=2016-09-16T00:00:00.00Z”

Returns

a new ConnectionParams object.

static from_tuples(*tuples: Any) → pip_services3_components.connect.ConnectionParams.ConnectionParams

Creates a new ConnectionParams object filled with provided key-value pairs called tuples. Tuples parameters contain a sequence of key1, value1, key2, value2, … pairs.

Parameters

tuples – the tuples to fill a new ConnectionParams object.

Returns

a new ConnectionParams object.

get_discovery_key() → str

Gets the key to retrieve this connection from DiscoveryService. If this key is null, than all parameters are already present.

Returns

the discovery key to retrieve connection.

get_host() → str

Gets the host name or IP address.

Returns

the host name or IP address.

get_port() → int

Gets the port number.

Returns

the port number.

get_port_with_default(default_port: int) → int

Gets the port number with default value.

Parameters

default_port – a default port number.

Returns

the port number.

get_protocol() → str

Gets the connection protocol.

Returns

the connection protocol or the default value if it’s not set.

get_protocol_with_default(default_value: str = None) → str

Gets the connection protocol with default value.

Parameters

default_value – (optional) the default protocol

Returns

the connection protocol or the default value if it’s not set.

get_uri() → str

Gets the resource URI or connection string. Usually it includes all connection parameters in it.

Returns

the resource URI or connection string.

static many_from_config(config: pip_services3_commons.config.ConfigParams.ConfigParams) → List[pip_services3_components.connect.ConnectionParams.ConnectionParams]

Retrieves all ConnectionParams from configuration parameters from “connections” section. If “connection” section is present instead, than it returns a list with only one ConnectionParams.

Parameters

config – a configuration parameters to retrieve connections

Returns

a list of retrieved ConnectionParams

set_discovery_key(value: str)

Sets the key to retrieve these parameters from DiscoveryService.

Parameters

value – a new key to retrieve connection.

set_host(value: str)

Sets the host name or IP address.

Parameters

value – a new host name or IP address.

set_port(value: int)

Sets the port number.

Parameters

value – a new port number.

set_protocol(value: str)

Sets the connection protocol.

Parameters

value – a new connection protocol.

set_uri(value: str)

Sets the resource URI or connection string.

Parameters

value – a new resource URI or connection string.

use_discovery() → bool

Checks if these connection parameters shall be retrieved from DiscoveryService. The connection parameters are redirected to DiscoveryService when discovery_key parameter is set.

Returns

true if connection shall be retrieved from DiscoveryService

class pip_services3_components.connect.ConnectionResolver(config: pip_services3_commons.config.ConfigParams.ConfigParams = None, references: pip_services3_commons.refer.IReferences.IReferences = None)

Bases: pip_services3_commons.config.IConfigurable.IConfigurable, pip_services3_commons.refer.IReferenceable.IReferenceable

Helper class to retrieve component connections.

If connections are configured to be retrieved from IDiscovery, it automatically locates IDiscovery in component references and retrieve connections from there using discovery_key parameter.

### Configuration parameters ###
  • connection:

    • discovery_key: (optional) a key to retrieve the connection from IDiscovery

    • … other connection parameters

  • connections: alternative to connection

    • [connection params 1]: first connection parameters

    • … connection parameters for key 1

    • [connection params N]: Nth connection parameters

    • … connection parameters for key N

### References ###

  • *:discovery:*:*:1.0 (optional) IDiscovery services to resolve connections

Example:

config = ConfigParams.from_tuples("connection.host", "10.1.1.100", "connection.port", 8080)

connectionResolver = ConnectionResolver()
connectionResolver.configure(config)
connectionResolver.set_references(references)
connectionResolver.resolve("123")
add(connection: pip_services3_components.connect.ConnectionParams.ConnectionParams)

Adds a new connection to component connections

Parameters

connection – new connection parameters to be added

configure(config: pip_services3_commons.config.ConfigParams.ConfigParams)

Configures component by passing configuration parameters.

Parameters

config – configuration parameters to be set.

get_all() → List[pip_services3_components.connect.ConnectionParams.ConnectionParams]

Gets all connections configured in component configuration. Redirect to Discovery services is not done at this point. If you need fully fleshed connection use resolve() method instead.

Returns

a list with connection parameters

register(correlation_id: Optional[str], connection: pip_services3_components.connect.ConnectionParams.ConnectionParams)

Registers the given connection in all referenced discovery services. This method can be used for dynamic service discovery.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • connection – a connection to register.

resolve(correlation_id: Optional[str]) → Optional[pip_services3_components.connect.ConnectionParams.ConnectionParams]

Resolves a single component connection. If connections are configured to be retrieved from Discovery service it finds a IDiscovery and resolves the connection there.

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

Returns

resolved connection parameters or null if nothing was found.

resolve_all(correlation_id: Optional[str]) → List[pip_services3_components.connect.ConnectionParams.ConnectionParams]

Resolves all component connection. If connections are configured to be retrieved from Discovery service it finds a IDiscovery and resolves the connection there.

Parameters

correlation_id – (optional) transaction id to trace execution through call chain.

Returns

a list of resolved connections.

set_references(references: pip_services3_commons.refer.IReferences.IReferences)

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

class pip_services3_components.connect.ConnectionUtils

Bases: object

A set of utility functions to process connection parameters

static compose_uri(options: pip_services3_commons.config.ConfigParams.ConfigParams, default_protocol: str, default_port: int) → str

Composes URI from config parameters. The result URI will be in the following form: protocol://username@password@host1:port1,host2:port2,…?param1=abc&param2=xyz&…

Parameters

  • options – configuration parameters

  • default_protocol – a default protocol

  • default_port – a default port

Returns

a composed URI

static concat(options1: pip_services3_commons.config.ConfigParams.ConfigParams, options2: pip_services3_commons.config.ConfigParams.ConfigParams, *keys: str) → pip_services3_commons.config.ConfigParams.ConfigParams

Concatinates two options by combining duplicated properties into comma-separated list

Parameters

  • options1 – first options to merge

  • options2 – second options to merge

  • keys – when define it limits only to specific keys

static exclude(options: pip_services3_commons.config.ConfigParams.ConfigParams, *keys: str) → pip_services3_commons.config.ConfigParams.ConfigParams

Excludes specified keys from the config parameters.

Parameters

  • options – configuration parameters to be processed.

  • keys – a list of keys to be excluded.

Returns

a processed config parameters.

static include(options: pip_services3_commons.config.ConfigParams.ConfigParams, *keys: str) → pip_services3_commons.config.ConfigParams.ConfigParams

Includes specified keys from the config parameters.

Parameters

  • options – configuration parameters to be processed.

  • keys – a list of keys to be included.

Returns

a processed config parameters.

static parse_uri(uri: str, default_protocol: str, default_port: str) → pip_services3_commons.config.ConfigParams.ConfigParams

Parses URI into config parameters. The URI shall be in the following form: protocol://username@password@host1:port1,host2:port2,…?param1=abc&param2=xyz&…

Parameters

  • uri – the URI to be parsed

  • default_protocol – a default protocol

  • default_port – a default port

Returns

a configuration parameters with URI elements

class pip_services3_components.connect.DefaultDiscoveryFactory

Bases: pip_services3_components.build.Factory.Factory

Creates IDiscovery components by their descriptors.

See Factory, IDiscovery, MemoryDiscovery,

MemoryDiscoveryDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>
class pip_services3_components.connect.IDiscovery

Bases: abc.ABC

Interface for discovery services which are used to store and resolve connection parameters to connect to external services.

register(correlation_id: Optional[str], key: str, connection: pip_services3_components.connect.ConnectionParams.ConnectionParams) → pip_services3_components.connect.ConnectionParams.ConnectionParams

Registers connection parameters into the discovery service.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • key – a key to uniquely identify the connection parameters.

  • connection – a connection to be registered.

Returns

the registered connection parameters.

resolve_all(correlation_id: Optional[str], key: str) → List[pip_services3_components.connect.ConnectionParams.ConnectionParams]

Resolves all connection parameters by their key.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • key – a key to uniquely identify the connections.

Returns

a list with resolved connections.

resolve_one(correlation_id: Optional[str], key: str) → pip_services3_components.connect.ConnectionParams.ConnectionParams

Resolves a single connection parameters by its key.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • key – a key to uniquely identify the connection.

Returns

a resolved connection.

class pip_services3_components.connect.MemoryDiscovery(config: pip_services3_commons.config.ConfigParams.ConfigParams = None)

Bases: pip_services3_components.connect.IDiscovery.IDiscovery, pip_services3_commons.config.IReconfigurable.IReconfigurable

Discovery service that keeps connections in memory.

### Configuration parameters ###

  • [connection key 1]:

  • … connection parameters for key 1

  • [connection key 2]:

  • … connection parameters for key N

Example:

config = ConfigParams.from_tuples(
    "connections.key1.host", "10.1.1.100",
    "connections.key1.port", "8080",
    "connections.key2.host", "10.1.1.100",
    "connections.key2.port", "8082"
)

discovery = MemoryDiscovery()
discovery.configure(config)

connection = discovery.resolve_one("123", "key1")
# Result: host=10.1.1.100;port=8080
configure(config: pip_services3_commons.config.ConfigParams.ConfigParams)

Configures component by passing configuration parameters.

Parameters

config – configuration parameters to be set.

read_connections(connections: pip_services3_commons.config.ConfigParams.ConfigParams)

Reads connections from configuration parameters. Each section represents an individual Connection params

Parameters

connections – configuration parameters to be read

register(correlation_id: Optional[str], key: str, connection: pip_services3_components.connect.ConnectionParams.ConnectionParams) → pip_services3_components.connect.ConnectionParams.ConnectionParams

Registers connection parameters into the discovery service.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • key – a key to uniquely identify the connection parameters.

  • connection – a connection to be registered.

Returns

the registered connection parameters.

resolve_all(correlation_id: Optional[str], key: str) → List[pip_services3_components.connect.ConnectionParams.ConnectionParams]

Resolves all connection parameters by their key.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • key – a key to uniquely identify the connections.

Returns

a list with resolved connections.

resolve_one(correlation_id: Optional[str], key: str) → pip_services3_components.connect.ConnectionParams.ConnectionParams

Resolves a single connection parameters by its key.

Parameters

  • correlation_id – (optional) transaction id to trace execution through call chain.

  • key – a key to uniquely identify the connection.

Returns

a resolved connection.