Metadata-Version: 2.5
Name: smthng-core
Version: 0.2.0
Summary: Environment-agnostic core engine for smthng peer-to-peer file transfer.
Project-URL: Homepage, https://github.com/alsabur20/smthng
Project-URL: Repository, https://github.com/alsabur20/smthng
Project-URL: Changelog, https://github.com/alsabur20/smthng/blob/main/packages/core/CHANGELOG.md
Project-URL: Issues, https://github.com/alsabur20/smthng/issues
Author-email: Abdul Sabur <alsabur20@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: chunking,file-transfer,p2p,peer-to-peer,protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: File Sharing
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.9
Description-Content-Type: text/markdown

# smthng-core

The environment-agnostic engine behind [smthng](https://github.com/alsabur20/smthng),
a peer-to-peer file transfer system.

This package holds the entire transfer protocol — chunking, SHA-256 verification,
Pydantic-validated messages, and the sender/receiver state machines. It performs
no I/O and imports no framework. Every client (CLI, web, mobile) supplies a
transport and a pair of file handles, and shares everything else.

```bash
pip install smthng-core
```

## What is in here

| Module | Responsibility |
| --- | --- |
| `framing` | The 10-byte frame header every peer agrees on |
| `chunking` | Splitting a file into fixed-size pieces |
| `hashing` | SHA-256 over buffers and streams |
| `manifest` | `FileManifest` — validated, and the security boundary for filenames |
| `protocol` | Control messages (`Offer`, `Accept`, `Complete`, …) and chunk payloads |
| `transport` | The `Transport` protocol, plus `StreamTransport` for byte streams |
| `session` | `SenderSession` and `ReceiverSession` — the state machines |
| `files` | Structural types for the file I/O the engine drives |
| `testing` | In-memory transport pair and a buffer-backed receiver policy |

## The protocol

```
sender                          receiver
  |  Offer(manifest)  ------------->  |   "here is what I have"
  |  <-------------  Accept | Reject  |   "send it" / "no, because..."
  |  DATA chunk 0     ------------->  |
  |  DATA chunk 1     ------------->  |   (one frame per chunk)
  |  ...                              |
  |  Complete(sha256) ------------->  |   "that was all of it"
  |  <-------------  Ack | Abort      |   "verified" / "integrity failed"
```

Integrity is checked twice: every chunk carries its own SHA-256, so a corrupted
frame is caught on arrival, and the reassembled file is verified against the
manifest before the receiver commits it to disk.

## Sending a file

```python
import asyncio
from pathlib import Path

from smthng_core import SenderSession, StreamTransport, build_manifest


async def send(path: Path, transport):
    with path.open("rb") as handle:
        manifest = build_manifest(path.name, path.stat().st_size, handle)
        await SenderSession(transport).send(manifest, handle)
```

## Receiving a file

Implement `ReceiverPolicy` to decide whether to accept an offer and where the
bytes land. Exactly one of `commit` or `discard` is always called, so a failed
transfer never leaves a half-written file in place.

```python
from smthng_core import ReceiverSession

manifest = await ReceiverSession(transport).receive(policy)
```

## Writing a new transport

Implement two `async` methods over whatever moves your bytes:

```python
class MyTransport:
    async def send(self, frame: Frame) -> None: ...
    async def receive(self) -> Frame: ...
    async def aclose(self) -> None: ...
```

For a byte stream (TCP, TLS, a serial port) implement `ByteStream` instead and
wrap it in `StreamTransport`, which adds the length-prefix framing for you.
`smthng_core.testing.memory_transport_pair()` lets you exercise your adapter
against the real protocol without a network.

## License

MIT
