Initial code commit

.flake8

@@ -0,0 +1,6 @@
+[flake8]
+doctests = True
+filename = *.py
+exclude = .venv,.git,.tox,dist,doc,*lib/python*,*egg,build,*web-server/*,
+ignore = E121,E123,E126,E203,E226,E501,W503,E704
+max-line-length = 88

.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Default owners for everything in the repo. These users will be requested for
+# review when someone opens a pull request.
+* @webbnh

.gitignore

@@ -157,4 +157,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
+
+# editors
+*~

README.md

@@ -1,2 +1,42 @@
 # file-relay
+
 Simple HTTP-based ad-hoc file relay utility with a RESTful interface
+[![Build status](https://github.com/distributed-system-analysis/file-relay/actions/workflows/ci.yml/badge.svg)](https://github.com/distributed-system-analysis/file-relay/actions/workflows/ci.yml)
+[![Unit test code coverage](https://badgen.net/codecov/c/github/distributed-system-analysis/file-relay)](https://codecov.io/gh/distributed-system-analysis/file-relay)
+
+This repo provides a single-file Python script which uses the Bottle web server framework to stand up an ad-hoc
+web server with a simple RESTful interface for transferring files between two clients.  This is of particular
+utility if the clients are behind separate firewalls and cannot directly connect to each other.
+
+The emphasis is on simplicity, and the expectation is that the service this program provides is transient.  That
+is, when a user needs to transfer a file, they would start the program on a host which both clients can reach,
+perform the file transfer, and then shut down the service.
+
+This service is not intended to be "industrial strength", it doesn't use or require credentials for access, and
+it's not highly optimized.  If you want those things, consider using a commercial S3 service.
+
+That said, it _is_ intended to work on a public-facing network.  A modest level of security is provided by using
+"unguessable" values for the components of the URIs.  The first is the "server ID" which is provided to the command
+invocation when the utility is started.  If this is a sufficiently long string of arbitrary characters, it should
+provide all the same protections as a bearer token, meaning that only clients which know the ID will be able to
+access the service.  Analogously, resources (i.e., files) on the service are referenced using the SHA 256 hash of
+their contents.  This prevents collisions between uploaded files, and it means that a file can only be accessed by
+someone who knows that it is there (and, doing so allows the utility to confirm the file integrity on upload, and
+clients can do the same on download, without having to provide additional headers on the requests or responses).
+
+This utility currently offers five methods:
+
+- `PUT /<server_id>/<file_id>`: upload a file
+- `GET /<server_id>/<file_id>`: download a file
+- `DELETE /<server_id>/<file_id>`: remove an uploaded file
+- `GET /<server_id>`: return server status
+- `DELETE /<server_id>`: request server shutdown
+
+There are a number of tweaks which are expected to be added:
+- The hash algorithm for resource names may be changed or made configurable
+- The underlying web server may be changed from the reference one to Gunicorn or other
+- The web server should be made able to accept SSL connections
+- The utility needs to be packaged, either as a Python package or a container (or both)
+- Figure out what the server status response _should_ contain -- currently, it provides
+a list of the available files, which undermines the "ya gotta know it's there" story.
+

pyproject.toml

@@ -0,0 +1,10 @@
+[tool.black]
+skip-string-normalization = false
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"                 # black-compatible (e.g., trailing comma)
+known_first_party = ["relay"]     # use separate section for project sources
+multi_line_output = 3             # "hanging" indent with dedented paren
+force_sort_within_sections = true # don't separate import vs from
+order_by_type = false             # sort alphabetic regardless of case

relay/__init__.py

@@ -0,0 +1 @@
+# relay - a simple HTTP-based ad-hoc file relay utility with a RESTful interface