Library / SDK
openstack/swift avatar
openstack/swift

Swift's mirror carries the review machinery of the system that no longer reviews it, and its tests skip on the wrong filesystem

OpenStack Storage (Swift). Mirror of code maintained at opendev.org.

2,804 stars1,070 forksPythonApache-2.0

At a glance

What is it?
A distributed object store built for multi-tenancy and high concurrency, whose Python source tree documents its own internals in unusual detail. This GitHub copy has no releases, and a green test run on a filesystem without large xattr support is not a full test run.
Who is it for?
Read this as a reference implementation rather than as the place to file issues. The source tree is unusually honest about itself, which is its main value here: it names the three test suites and what each one proves, it states the filesystem requirement that makes a test run complete, it annotates every dependency pin with its licence, and it spells out the request path from the proxy entry point to a controller.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • openstack/swift2,804 ★ · +1
Star history
Repository2026-10-042026-11-21
openstack/swift2.8k2.8k

1 Stars in the last 48 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A mirror with no releases and a full set of review files

This repository describes itself as a mirror of code maintained at opendev.org, and it has no GitHub releases at all.

The homepage points at `opendev.org/openstack/swift`, the project description names opendev.org as the place the code is actually maintained, and the documentation paragraph says the docs are auto-generated after every commit and published at `docs.openstack.org/swift/latest/`. So the canonical artefacts, the docs and the release tags, all live in the upstream system, and this tree is a copy.

What is odd is how much of the upstream machinery came along with the copy. The top level includes `.gitreview`, which is the Gerrit hook configuration, along with `.mailmap`, `.zuul.yaml` for the CI system, `REVIEW_GUIDELINES.rst`, `releasenotes/`, `roles/` for Ansible and `bandit.yaml` for a security linter. A mirror does not review, does not gate on Zuul and does not cut release notes, so those files describe a process that runs somewhere else.

The documentation text is consistent with that. Contributors are pointed at OpenStack's shared code contribution, review and testing processes, and at `CONTRIBUTING.rst`. The tree still carries an `AUTHORS` file, a `CHANGELOG`, a `LICENSE` and a `README.rst`, so nothing here is a stub, but the version history a reader would look for is not in this tree.

A green test run on the wrong filesystem skips a large number of tests

One sentence in the developer documentation changes how you should read any test result.

To fully run the tests, the target environment must use a filesystem that supports large xattrs, with XFS strongly recommended. For unit tests and in-process functional tests, either mount `/tmp` with XFS or provide another XFS filesystem through the `TMPDIR` environment variable. And then the clause that matters: without this setting, tests should still pass, but a very large number will be skipped.

So the default failure mode is a green run that is not a run. The suite may report success while skipping tests that need larger extended attributes, so inspect the skip count and reasons. The same property the object server relies on for its own metadata is the property the test suite needs, which means a filesystem that quietly truncates or refuses large xattrs gives you a development machine that both passes tests and loses metadata.

The recommendation is XFS specifically, and the escape hatch is narrow: the documented setup uses XFS for `/tmp` or points `TMPDIR` at XFS; the underlying requirement is support for large extended attributes. That is a setup step before the first test run, not something discovered later.

The compensating control is the suite's own shape, described in the next section, because the three test types fail in different ways and catch different mistakes.

Three test types that prove different things, run by four dotfiles

The suite is split by what each test is allowed to know, and the entry points are four files at the repository root.

Unit tests check that small sections of the code behave properly, for example a single function against various inputs, validating that the code is correct and regressions are not introduced. Functional tests check that the client API is working as expected, and they are described as runnable against any endpoint claiming to support the Swift API, with some requiring multiple accounts at different privilege levels. They are black box tests whose stated purpose is to ensure client applications written against Swift continue to work. Probe tests are the white box half: they validate the internal workings of a Swift cluster, are written against the SAIO development environment, and the worked example is creating an object, deleting one replica and checking that the background consistency processes find and correct the error.

Run them with `.unittests`, `.functests` and `.probetests`, and `.alltests` wraps the other three. All four are committed at the top level as dotfiles rather than living in a `bin/` directory, so the invocation is a path to a file in the checkout root.

Two consequences for a deployer. Functional tests against a real cluster require `/etc/swift/test.conf`, with a sample at `test/sample.conf` in the tree, so running them reaches outside the checkout to a system-wide path. And probe tests are tied to a single node SAIO cluster, so they are a development tool rather than something you point at production.

Every dependency pin carries a licence, and three versions are excluded by hand

The requirements file doubles as a licence inventory, which is unusual enough to be worth reading line by line.

Each pin is annotated with its licence in a trailing comment: `eventlet>=0.25.0,!=0.34.3` marked MIT, `requests>=2.14.2` marked Apache-2.0, `PyECLib>=1.3.1,!=1.6.2,!=1.6.3` marked BSD, `cryptography>=2.0.2` marked BSD/Apache-2.0, `xattr>=0.7.2;sys_platform!='win32'` marked MIT, and `dnspython>=1.15.0` annotated with its own licence URL rather than a name.

Three specific versions are excluded by hand across two pins: eventlet 0.34.3, and PyECLib 1.6.2 and 1.6.3. Nobody recorded here why those three are ruled out, so a reader has to treat them as known bad rather than as documented problems.

The xattr line carries the only environment marker in the file, `sys_platform!='win32'`, which means the extended attribute library is not installed on Windows at all. That follows from what the object server does, and it is the clearest statement in the file about which platforms this code targets.

The annotation is partial rather than complete: `greenlet>=0.4.14`, `PasteDeploy>=2.0.0` and `lxml>=4.2.3` carry no licence comment, so the file tracks the licences of six of its nine direct dependencies. With `lower-constraints.txt`, `test-requirements.txt` and `tox.ini` alongside it, the pinning story is thorough on versions and partial on provenance.

The container build pins Alpine 3.16.2 and hardcodes amd64

The Dockerfile in the tree is a single node all-in-one image, and several of its choices are visible in the lines themselves.

dockerfile
FROM        alpine:3.16.2
MAINTAINER  Openstack Swift

ENV         ARCH amd64
ENV         BUILD_DIR "/tmp"

`ARCH` is set to amd64 as a build argument inside the image, and the two overlay archives added later are fetched with that value interpolated into their download URLs, so the image is single-architecture by construction rather than by documentation. The base is pinned to one Alpine release, which means the image inherits that release's package versions for everything the install scripts pull in.

`MAINTAINER` is a Docker directive that has been deprecated for years, and it is still the only place the image declares who looks after it.

The install itself is a chain of numbered shell scripts, `00_swift_needs.sh`, `10_apk_install_prereqs.sh`, `21_apk_install_py3.sh` and `50_swift_install.sh`, invoked in order inside a single `RUN` with echo separators between them. The numbering is the dependency ordering, and the scripts live under `docker/install_scripts`, referenced by a `COPY` line that is present but commented out, so the copy happens through the `COPY . /opt/swift` line instead. A `.dockerignore` at the top level keeps the build context down.

Both overlay archives are added over HTTPS from GitHub releases at versions pinned through environment variables, and a `.sig` file is fetched next to the first one. The lines shown download the signature without showing anything that uses it.

setup.py is a shim and pbr holds the version and the metadata

The packaging is two files, and one of them does almost nothing.

`pyproject.toml` carries the build system declaration: it requires `pbr>=6.0.0` and `setuptools>=64`, and names `pbr.build` as the backend. `setup.py` imports setuptools and calls it with `setup_requires=['pbr']` and `pbr=True`, under a copyright header naming Hewlett-Packard Development Company and the year 2013.

So all the real work is delegated to pbr, which reads version and metadata from elsewhere rather than from a literal in either file, and the 2013 header is a leftover from when this shim was written. There is also a small inconsistency worth knowing if you debug an install: `setup.py` asks for `pbr` with no version at all while `pyproject.toml` requires `pbr>=6.0.0`, so the constraint that actually binds is the one in the newer file.

The rest of the packaging surface is spread across the top level in the way OpenStack projects usually arrange it: `MANIFEST.in` and `setup.cfg` for the sdist, `bindep.txt` for operating system level packages rather than Python ones, `bandit.yaml` for the static security check, `tox.ini` for multi-environment runs, and `.stestr.conf` and `.coveragerc` for the test and coverage tooling. `api-ref/` sits in the tree as well, which makes the API reference available both here and at `docs.openstack.org/api-ref/object-store/`.

The request path starts in proxy/server.py and the docs ship config snippets

The one part of the architecture the README describes concretely is the request path, and it is short enough to hold in your head.

Swift is a WSGI application and uses eventlet's WSGI server. Once the processes are running, the entry point for new requests is the `Application` class in `swift/proxy/server.py`. From there a controller is chosen and the request is processed, and the proxy may choose to forward the request to a back-end server. The entry point for object server requests is the `ObjectController` class in `swift/obj/server.py`.

So proxy and object server are two named classes in two named files, and the proxy is the only component in the path that decides whether a request stays or moves. That is the whole routing story, and it is documented here while the operational detail is not.

The code organisation section fills in the rest. `swift/` holds the core, split into `account/`, `container/`, `obj/` and `proxy/` as the servers, plus `cli/` for the code backing some command line tools, `common/` for code shared between modules, and inside that `middleware/` for what is called standard, officially-supported middleware and `ring/` for the ring implementation. `locale/` holds translation data.

Outside the core, `etc/` is sample config files, `examples/` is config snippets used in the documentation with `apache2/` and `wsgi/` subdirectories, and `test/` is where the three suites live. The documentation build is two commands:

shell
pip install -r requirements.txt -r doc/requirements.txt
sphinx-build -W -b html doc/source doc/build/html

The `-W` flag turns warnings into errors, so a documentation warning fails the build.

Editorial conclusion

Read this as a reference implementation rather than as the place to file issues. The source tree is unusually honest about itself, which is its main value here: it names the three test suites and what each one proves, it states the filesystem requirement that makes a test run complete, it annotates every dependency pin with its licence, and it spells out the request path from the proxy entry point to a controller. Anyone building or operating a Swift cluster will spend time in exactly these files. Before you rely on any of it, settle three things. Where you will actually get the code and the releases, since this tree is a mirror with none of its own and the documentation is generated from the upstream commits. Whether your filesystem can hold the large extended attributes the object server needs, because the same property that makes a skipped test suite pass quietly is the one your data path depends on. And which dependencies you are inheriting, including an xattr pin that is excluded on Windows and three specific versions ruled out by hand. The Apache-2.0 licence and the 2010 open sourcing history are the least surprising parts.

Frequently asked questions

What is OpenStack Swift used for?

It is a distributed object storage system designed to scale from a single machine to thousands of servers, optimized for multi-tenancy and high concurrency, and named as suited to backups, web and mobile content and other unstructured data that can grow without bound.

Where is the real OpenStack Swift source code kept?

At opendev.org/openstack/swift. This repository describes itself as a mirror of the code maintained there, it has no releases of its own, and the documentation is generated from the upstream commits and published at docs.openstack.org/swift/latest/.

How do you run the OpenStack Swift test suites?

Through four files at the repository root: .unittests, .functests and .probetests, plus .alltests which wraps the other three. A full run needs a filesystem supporting large xattrs, XFS strongly recommended, supplied either by mounting /tmp with XFS or by pointing TMPDIR at one.

What are probe tests in OpenStack Swift?

White box tests that validate the internal workings of a Swift cluster, written against the SAIO development environment. The worked example creates an object, deletes one replica and checks that the background consistency processes find and correct the error.

Which Python packages does OpenStack Swift require?

eventlet at 0.25.0 or newer but not 0.34.3, greenlet, PasteDeploy, lxml, requests, xattr on platforms other than Windows, PyECLib at 1.3.1 or newer but not 1.6.2 or 1.6.3, cryptography, and dnspython.

How does an OpenStack Swift request get routed?

Swift is a WSGI application on eventlet's WSGI server. The entry point is the Application class in swift/proxy/server.py, a controller is chosen from there, the proxy may forward the request to a back-end server, and the object server's own entry point is the ObjectController class in swift/obj/server.py.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. openstack/swift on GitHub
  4. Project website
  5. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/openstack-swift.svg)](https://hysenlabs.com/projects/openstack-swift)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/openstack-swift.svg)](https://hysenlabs.com/projects/openstack-swift)

Was this useful?