Metadata-Version: 2.4
Name: haps-runtime-remotessh
Version: 0.4.1
Summary: Give a HAPS RuntimeJob the tools to talk to an HPC centre over SSH
Author: Logica Team, Universite de Rennes / IRISA
Author-email: Benjamin De Zordo <benjamin.de-zordo@irisa.fr>
License-Expression: MIT
Project-URL: Homepage, https://www.irisa.fr/equipes/logica
Keywords: haps,hpc,ssh,distributed-computing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Clustering
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: haps-runtime-executor==0.4.*
Requires-Dist: remotemanager<0.15,>=0.14
Requires-Dist: pydantic>=2.10
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# haps-runtime-remotessh

**This is not a HAPS plugin.** No tag, no metadata, no client half.

It is one class, `RemoteSSHJob`, which extends `RuntimeJob` from
`haps-runtime-executor` and gives it what it needs to talk to an HPC centre over
SSH. A maintainer imports it, subclasses it, and writes `execute`.

SSH is currently done with [RemoteManager](https://l_sim.gitlab.io/remotemanager/).
Nothing outside `remote.py` knows that, so it can be swapped later.

```bash
pip install haps-runtime-remotessh
```

## Configure the centre

```toml
[hpc]
host     = "idris-ssh"
user     = "user"
passfile = "/home/user/.vault/idris_pass"   # chmod 600, yours
```

Optional: `keyfile` instead of `passfile`, `workdir_root` for a directory per
job, and five timeouts. See `HpcConfig` for the whole list.

`HpcConfig.from_toml` reads the `[hpc]` table and ignores the rest of the file.

## Write a job

```python
from haps_runtime import HapsClient
from haps_runtime_executor import RuntimeService
from haps_runtime_remotessh import HpcConfig, RemoteSSHJob


class DiskUsage(RemoteSSHJob):
    def execute(self) -> None:
        self.free = self.remotessh.run(["df", "-h", "/scratch"]).stdout

    def voutput(self, index: int, name: str) -> str:
        return self.free


config = HpcConfig.from_toml("hpc.toml")
RuntimeService(runtime, DiskUsage, config=config).start()
```

A full example is in `exemple/`.

## What you get

`RemoteSSHJob` adds two steps in front of the usual ones:

```
connect → setup directories → fetch arguments → fetch ebuffer inputs
        → execute → push results → push ebuffer outputs
```

| | |
|---|---|
| `self.remotessh` | the centre, ready to use |
| `self.workdir` | `workdir_root/<job uuid>`, or `None` |
| `self.hpc` | the configuration in use |

And on `self.remotessh`:

```python
run(argv, *, timeout=None) -> CommandResult   # returncode, stdout, stderr, ok
put(local: Path, remote: PurePosixPath)
get(remote: PurePosixPath, local: Path)
write_text(remote: PurePosixPath, text: str)
mkdir(remote)   exists(remote) -> bool   is_dir(remote) -> bool
size_of(remote) -> int | None
```

## Three things to know

**`run` takes argv, never a shell string.** No pipe, no redirection, no `$VAR`.
An argument that would need quoting is refused rather than mangled. Write paths
out in full, and put anything needing a shell in a script on the centre.

**Nothing is deleted on the centre.** `cleanup` releases the connection and
leaves `self.workdir` alone. Remove it yourself if you want it gone.

**Errors are yours to interpret.** A failed `connect` becomes a
`RuntimeServiceError`, because an unreachable centre would fail every job.
Everywhere else a `RemoteSSHError` reaches you untouched: only you know whether
a failed `put` condemns the job.

## Licence

MIT
