livery.git._ssh¶
livery.git._ssh ¶
One ssh connection per remote host, shared by every git the library spawns.
Every network git call opens a fresh ssh connection, and the handshake
is about half of a quiet fetch. OpenSSH multiplexes connections over
one master when ControlMaster is on: livery.git.ssh_environment
builds the GIT_SSH_COMMAND that turns it on for a spawned git, with
the sockets in one owner-only directory, and a master lingers for the
idle window so the next verb reuses it.
Two fixed names in the socket directory are the whole memory: the
socket itself, <user>@<host>:<port>, which is the proof a master is
up, and unsupported, written with ssh's words when a probe found
multiplexing broken on this host, which every later call reads first.
Delete the file to probe again.
Functions:
| Name | Description |
|---|---|
ssh_sockets |
Where the plugin keeps its sockets: |
ssh_command |
The |
ssh_environment |
The environment that multiplexes a spawned git's ssh, or why not. |
record_unsupported |
Turn multiplexing off under socket_dir with words; the file written. |
remote_host |
The user, host and port an ssh remote url names; None for any other transport. |
master_up |
Whether a master for url's host is up under socket_dir. |
Attributes:
| Name | Type | Description |
|---|---|---|
UNSUPPORTED |
|
|
SOCKET |
|
ssh_sockets ¶
Where the plugin keeps its sockets: ssh under the runner's data_dir.
The data directory is owner-only and durable, which a socket wants, and short enough on every platform for the socket path limit below.
Source code in packages/git/src/livery/git/_ssh.py
ssh_command ¶
The GIT_SSH_COMMAND that multiplexes over a master under socket_dir.
ControlMaster=auto reuses a master when one is up and opens one
otherwise, replacing a stale socket from an unclean exit; two
spawns racing to open a master is allowed, one wins and the other
connects directly. ControlPersist=<idle> keeps the master that
long after the last client. The path is quoted twice over: git
hands the command to a shell, and ssh then splits an option's
value on spaces unless it is double-quoted, and footman's data
directory on macOS has a space in it.
Source code in packages/git/src/livery/git/_ssh.py
ssh_environment ¶
ssh_environment(socket_dir: Path, *, idle: str = '10m', environ: Mapping[str, str] | None = None, configured: str = '') -> tuple[dict[str, str], str]
The environment that multiplexes a spawned git's ssh, or why not.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
socket_dir
|
Path
|
Where the sockets live; owner-only and short. |
required |
idle
|
str
|
How long a master lingers after its last client, in ssh's
own spelling ( |
'10m'
|
environ
|
Mapping[str, str] | None
|
The environment the spawn would inherit; the process's own when omitted. |
None
|
configured
|
str
|
What git's |
''
|
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
The mapping to merge into the spawn's environment, holding |
str
|
|
tuple[dict[str, str], str]
|
the reason multiplexing is not used. The reason is empty when |
tuple[dict[str, str], str]
|
the person's own setting won, which is theirs to know about. |
Source code in packages/git/src/livery/git/_ssh.py
record_unsupported ¶
Turn multiplexing off under socket_dir with words; the file written.
Source code in packages/git/src/livery/git/_ssh.py
remote_host ¶
The user, host and port an ssh remote url names; None for any other transport.
Both spellings ssh remotes take: git@github.com:owner/repo.git
and ssh://git@host:2222/owner/repo.git. An http, https or
file remote opens no ssh connection.
Source code in packages/git/src/livery/git/_ssh.py
master_up ¶
Whether a master for url's host is up under socket_dir.
ssh -O check asks the master over its socket and opens no
connection; a remote that is not ssh has no master and answers
False.