Jocay
71 lines
2.9 KiB
Markdown
71 lines
2.9 KiB
Markdown
# Repository guidance
|
|
|
|
## Project overview
|
|
|
|
WebSSH is a Python 3.10+ web SSH client. Tornado serves the HTTP and WebSocket
|
|
endpoints, Paramiko manages SSH connections, and xterm.js renders the terminal
|
|
in the browser.
|
|
|
|
## Repository layout
|
|
|
|
- `webssh/main.py`: application entry point and route wiring.
|
|
- `webssh/handler.py`: HTTP/WebSocket handlers and SSH connection setup.
|
|
- `webssh/worker.py`: asynchronous relay between Tornado and Paramiko channels.
|
|
- `webssh/settings.py`: CLI options and application/server configuration.
|
|
- `webssh/auth.py`, `webssh/storage.py`, `webssh/crypto.py`: authentication and
|
|
persistent saved-connection data.
|
|
- `webssh/templates/` and `webssh/static/`: browser UI.
|
|
- `tests/`: pytest/unittest test suite; `tests/sshserver.py` provides the local
|
|
Paramiko-based integration server.
|
|
|
|
## Setup and development commands
|
|
|
|
Use Python 3.10, 3.11, or 3.12.
|
|
|
|
```bash
|
|
python -m pip install -r requirements.txt
|
|
python -m pip install -e .
|
|
python run.py # listens on 127.0.0.1:8888
|
|
python run.py --port=8888 --debug=True --data-dir=./data
|
|
```
|
|
|
|
Install test tools with `python -m pip install pytest pytest-cov ruff`. Before
|
|
handing off a change, run the checks relevant to it:
|
|
|
|
```bash
|
|
python -m pytest tests
|
|
python -m pytest tests/test_app.py # focused example
|
|
python -m pytest --cov=webssh
|
|
ruff check .
|
|
```
|
|
|
|
The legacy Flake8 configuration in `setup.cfg` uses a maximum line length of
|
|
79 and excludes tests and `__init__.py` files.
|
|
|
|
## Implementation constraints
|
|
|
|
- Do not block Tornado's IOLoop. Paramiko connection work is blocking and must
|
|
run through the existing handler `ThreadPoolExecutor` pattern.
|
|
- Preserve locking around auth data, saved connections, and host-key mutation;
|
|
these objects are accessed from multiple threads.
|
|
- New HTTP endpoints should include `MixinHandler`. Protect private endpoints
|
|
with `@tornado.web.authenticated` and retain the existing origin, XSRF, IP,
|
|
and session checks.
|
|
- Treat credentials, private keys, cookie secrets, and saved connection data as
|
|
sensitive. Never log or expose them to the browser. Persistent auth and
|
|
connection files must retain mode `0o600`.
|
|
- Keep saved-password encryption compatible with the cookie secret and do not
|
|
silently reuse a credential when host, port, or username changes.
|
|
- Keep changes compatible with all supported Python versions and avoid adding
|
|
dependencies unless the task requires them.
|
|
|
|
## Testing expectations
|
|
|
|
- Add or update focused tests for behavior changes and regressions.
|
|
- Use the local mock SSH server for SSH authentication and connection flows;
|
|
tests must not depend on external SSH hosts or network services.
|
|
- For frontend or WebSocket changes, cover both the server handler behavior and
|
|
the corresponding browser-side message contract when applicable.
|
|
- Do not commit generated runtime state such as `auth.json`, `connections.json`,
|
|
cookie secrets, coverage output, caches, or local data directories.
|