Metadata-Version: 2.4
Name: git-asgi
Version: 0.1
Summary: Git HTTP server as ASGI middleware according to spec.
Author-email: Jakob Zahn <jakob.zahn@mailbox.org>
Maintainer-email: Jakob Zahn <jakob.zahn@mailbox.org>
License-Expression: AGPL-3.0-only
Project-URL: documentation, https://codeberg.org/jbdyn/git-asgi/src/branch/main/README.md
Project-URL: source, https://codeberg.org/jbdyn/git-asgi
Project-URL: issues, https://codeberg.org/jbdyn/git-asgi/issues
Project-URL: changelog, https://codeberg.org/jbdyn/git-asgi/src/branch/main/CHANGELOG.md
Keywords: asgi,middleware,application,git,http,server
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: Unix
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asgiref
Requires-Dist: typing-extensions
Dynamic: license-file

# git-asgi

> Git HTTP server as ASGI middleware according to spec.


## Features

- [x] ASGI 3 middleware with ASGI 2 application compatibility
- [x] ready-to-use ASGI 3 application included
- [x] ready-to-use within ASGI frameworks
- [x] dumb Git HTTP protocol
- [x] smart Git HTTP protocol, optionally supporting dumb Git HTTP protocol requests
- [x] Git archive creation
- [x] enabling and disabling of reading, writing or archiving
- [x] compatible with both SHA1 and SHA256 repositories
- [x] flexible and attachable logging formatting
- [ ] custom server-side Git hooks
- [ ] fully tested
- [x] fully documented
- [x] fully typed
- [x] minimal dependencies: just the Python standard library, `asgiref` and `typing-extensions`
- [x] handcrafted with love ❤️, no AI has ever touched this repo


## Package

The package is named `git_asgi` and [available on PyPI](https://pypi.org/project/git_asgi) for your favorite Python package manager to download.


## Usage

### ASGI Server

The ASGI application is named `app`, located in the [`git_asgi.app`](./src/git_asgi/app.py) Python module and can be customized via optional environment variables with carefully chosen defaults.

```sh
GIT_ASGI_BASE=/path/to/repos \
GIT_ASGI_LOGGER=base.logger.name \
GIT_ASGI_LEVEL=git-logger-logging-level \
GIT_ASGI_FORMAT=git-request-logger-str-format \
GIT_ASGI_SMART=0-or-1 \
GIT_ASGI_DUMB=0-or-1 \
GIT_ASGI_UPLOAD=0-or-1 \
GIT_ASGI_RECEIVE=0-or-1 \
GIT_ASGI_ARCHIVE=0-or-1 \
GIT_ASGI_REQUEST=request-timeout-in-seconds \
GIT_ASGI_OVERLOAD=overload-timeout-in-seconds \
GIT_ASGI_CHUNK=chunk-size-in-bytes \
SERVER [OPTIONS] git_asgi.app:app
```

The term `SERVER` refers to your ASGI server of choice.

As the used `GitMiddleware` ASGI middleware needs an ASGI application, a small one is defined to support the `lifespan` protocol and to answer every HTTP request not handled by the `GitMiddleware` ASGI middleware with a `403 FORBIDDEN` HTTP response.


### ASGI Framework

The ASGI middleware is named `GitMiddleware`, located in the [`git_asgi.middleware`](./src/git_asgi/middleware.py) Python module and can be used analogously to this pseudocode:

```python
from asgi_framework import FrameworkApp
from git_asgi.middleware import GitMiddleware

# initialize ASGI framework app
app = FrameworkApp()

# extend app ...

# define mandatory base path
base = "/path/to/repos"

# add ASGI Git middleware alongside configuration arguments
# to ASGI framework app
app.add_middleware(GitMiddleware, base=base, **kwargs)

# run app ...
```

Please refer to the documentation of your ASGI framework of choice on how to include an ASGI middleware.

If you need to align the app routes with the ones `GitMiddleware` uses, you will find them defined as regular expressions in the same [`git_asgi.middleware`](./src/git_asgi/middleware.py) Python module as well.


## Development

This repository follows the [Python packaging standard](https://packaging.python.org/en/latest/) with a [`pyproject.toml`](./pyproject.toml) Python project configuration file.

Please refer to the documentation of your Python package manager of choice on how to install a possibly editable Python package from your obtained copy of the source code.

There is a `dev` dependency group defined, which you want to also install if you plan on developing on the code base.

After successful installation of all dependencies, you are able to run

```
prek install
```

to install pre-commit Git hooks helping with adhering to the code quality and style.


## AI

This repository is featuring only handcrafted lines of code and text.

No AI will ever be used to change its content.

No change requests with AI-written code will be accepted.

Why?
Despite being an arguably useful tool, AI comes with arguably unacceptable aspects:

- licensing: inferenced code is partially stolen code
- footprint: hugely negative environmental impact
- foresight: no concept of understanding fundamental ideas of a code base
- quality: hallucinations and tendency to extremely wordy output


## Windows

No special effort was put into making this software work on Windows.

There are a few lines of code which work on UNIX only.
However, this is considered to be a rare issue, since the ASGI middleware could be run in UNIX containers or in the Windows Subsystem for Linux (WSL) natively.

If you really need to run this code on bare Windows, test it, change it and make it available to the public as per the AGPL-3.0-only license.
If you think that your changes will be a beneficial contribution to the project, feel free to open a change request.


## Changelog

Project changes are documented in [CHANGELOG.md](./CHANGELOG.md)


## License

[AGPL-3.0-only](./LICENSE)
