smthng-core
The environment-agnostic engine behind 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.
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
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.
from smthng_core import ReceiverSession
manifest = await ReceiverSession(transport).receive(policy)
Writing a new transport
Implement two async methods over whatever moves your bytes:
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file smthng_core-0.2.0.tar.gz.
File metadata
- Download URL: smthng_core-0.2.0.tar.gz
- Upload date:
- Size: 25.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
071f000cef0cf0ee698d0c186269cc8a73e936f9c60134a654eca35908276470
|
|
| MD5 |
2cb9e4628b2bab39a4f56714622045c5
|
|
| BLAKE2b-256 |
12061c6cedd76d81a316aa9c6d519a2390ca5a358b05354773b976af52f633a9
|
Provenance
The following attestation bundles were made for smthng_core-0.2.0.tar.gz:
Publisher:
release-core.yml on alsabur20/smthng
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
smthng_core-0.2.0.tar.gz -
Subject digest:
071f000cef0cf0ee698d0c186269cc8a73e936f9c60134a654eca35908276470 - Sigstore transparency entry: 2611605073
- Sigstore integration time:
-
Permalink:
alsabur20/smthng@32f43a4739e779225a354cf73efde0d04b280dec -
Branch / Tag:
refs/tags/core-v0.2.0 - Owner: https://github.com/alsabur20
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release-core.yml@32f43a4739e779225a354cf73efde0d04b280dec -
Trigger Event:
push
-
Statement type:
File details
Details for the file smthng_core-0.2.0-py3-none-any.whl.
File metadata
- Download URL: smthng_core-0.2.0-py3-none-any.whl
- Upload date:
- Size: 22.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a376b22ff86b3d5cd2c736c6fe13c2835a2eb8eb118dd3b2149708e06334e8e6
|
|
| MD5 |
46999b031824112a9d45dc7214bba715
|
|
| BLAKE2b-256 |
07c5ddd8dae300564d2934df64d8fa685dc5ba029545b38bdd1ef6c96765c0d6
|
Provenance
The following attestation bundles were made for smthng_core-0.2.0-py3-none-any.whl:
Publisher:
release-core.yml on alsabur20/smthng
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
smthng_core-0.2.0-py3-none-any.whl -
Subject digest:
a376b22ff86b3d5cd2c736c6fe13c2835a2eb8eb118dd3b2149708e06334e8e6 - Sigstore transparency entry: 2611605160
- Sigstore integration time:
-
Permalink:
alsabur20/smthng@32f43a4739e779225a354cf73efde0d04b280dec -
Branch / Tag:
refs/tags/core-v0.2.0 - Owner: https://github.com/alsabur20
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release-core.yml@32f43a4739e779225a354cf73efde0d04b280dec -
Trigger Event:
push
-
Statement type:
