Metadata-Version: 2.4
Name: arrakis-server
Version: 0.11.0
Summary: Server implementation of the Arrakis low-latency timeseries data distribution platform
Project-URL: Homepage, https://git.ligo.org/ngdd/arrakis-server
Project-URL: Documentation, https://docs.ligo.org/ngdd/arrakis-server
Project-URL: Issue Tracker, https://git.ligo.org/ngdd/arrakis-server/issues
Project-URL: Source Code, https://git.ligo.org/ngdd/arrakis-server.git
Author-email: Olivia Godwin <olivia.godwin@ligo.org>
Maintainer-email: Olivia Godwin <olivia.godwin@ligo.org>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: arrakis>=0.12
Requires-Dist: gpstime
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: ruamel-yaml
Requires-Dist: sympy
Requires-Dist: toml
Requires-Dist: types-toml
Requires-Dist: typing-extensions
Provides-Extra: dev
Requires-Dist: markdown-callouts>=0.2; extra == 'dev'
Requires-Dist: markdown-exec>=0.5; extra == 'dev'
Requires-Dist: mkdocs-coverage>=0.2; extra == 'dev'
Requires-Dist: mkdocs-gen-files>=0.3; extra == 'dev'
Requires-Dist: mkdocs-literate-nav>=0.4; extra == 'dev'
Requires-Dist: mkdocs-material-igwn; extra == 'dev'
Requires-Dist: mkdocs-section-index>=0.3; extra == 'dev'
Requires-Dist: mkdocs>=1.3; extra == 'dev'
Requires-Dist: mkdocstrings[python]; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: mypy-extensions; extra == 'dev'
Requires-Dist: pip; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-freezer; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: toml>=0.10; extra == 'dev'
Provides-Extra: docs
Requires-Dist: markdown-callouts>=0.2; extra == 'docs'
Requires-Dist: markdown-exec>=0.5; extra == 'docs'
Requires-Dist: mkdocs-coverage>=0.2; extra == 'docs'
Requires-Dist: mkdocs-gen-files>=0.3; extra == 'docs'
Requires-Dist: mkdocs-literate-nav>=0.4; extra == 'docs'
Requires-Dist: mkdocs-material-igwn; extra == 'docs'
Requires-Dist: mkdocs-section-index>=0.3; extra == 'docs'
Requires-Dist: mkdocs>=1.3; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Requires-Dist: toml>=0.10; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mypy; extra == 'lint'
Requires-Dist: mypy-extensions; extra == 'lint'
Requires-Dist: pip; extra == 'lint'
Requires-Dist: ruff; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-freezer; extra == 'test'
Description-Content-Type: text/markdown

<h1 align="center">arrakis-server</h1>

<p align="center">Arrakis server</p>

<p align="center">
  <a href="https://git.ligo.org/ngdd/arrakis-server/-/pipelines/latest">
    <img alt="ci" src="https://git.ligo.org/ngdd/arrakis-server/badges/main/pipeline.svg" />
  </a>
  <a href="https://git.ligo.org/ngdd/arrakis-server/-/pipelines/latest">
    <img alt="ci" src="https://git.ligo.org/ngdd/arrakis-server/badges/main/coverage.svg" />
  </a>
  <a href="https://ngdd.docs.ligo.org/arrakis-server/">
    <img alt="documentation" src="https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat" />
  </a>
  <a href="https://pypi.org/project/arrakis-server/">
    <img alt="pypi version" src="https://img.shields.io/pypi/v/arrakis-server.svg" />
  </a>
</p>

---

Server implementation of the Arrakis low-latency timeseries data distribution
platform. Serve historical and live detector data to clients over Apache
Arrow Flight, either from a backend you provide or by acting as an
information server that routes requests to other Arrakis endpoints.

## Resources

* [Documentation](https://docs.ligo.org/ngdd/arrakis-server)
* [Source Code](https://git.ligo.org/ngdd/arrakis-server)
* [Issue Tracker](https://git.ligo.org/ngdd/arrakis-server/-/issues)
* [Arrakis Python client](https://git.ligo.org/ngdd/arrakis-python)

## Installation

With `pip`:

```
pip install arrakis-server
```

With Docker:

```
docker run --net=host -it containers.ligo.org/ngdd/arrakis-server:latest
```

## Where to Start

* **[Tutorial](https://ngdd.docs.ligo.org/arrakis-server/tutorials/getting-started/)** — New to arrakis-server? Run a mock server and connect a client step by step.
* **[User Guide](https://ngdd.docs.ligo.org/arrakis-server/user/)** — Running the server, configuring backends, scope maps, multi-backend deployments, and production tips.
* **[Background](https://ngdd.docs.ligo.org/arrakis-server/background/architecture/)** — How the server works: Flight dispatch, the backend trait, retention-based routing, and the metadata model.
* **[API Reference](https://ngdd.docs.ligo.org/arrakis-server/reference/)** — Auto-generated documentation from source code.

## Features

* Pluggable backends via Python entry points
* Built-in mock backend for local testing and CI
* Information-server mode that routes requests across multiple endpoints
* Retention-aware request routing, splitting time ranges across live and
  historical backends
* Time-valued channel metadata for evolving detector configurations
* Publish and partition endpoints for Kafka-backed publishing backends

## Quickstart

### Run a mock server

The mock backend generates synthetic timeseries for a predefined set of H1
and L1 channels:

```
arrakis-server mock
```

Then connect with the [Arrakis client CLI](https://git.ligo.org/ngdd/arrakis-python):

```
arrakis find "H1:.*"
```

### Serve custom mock channels

Pass one or more TOML files defining your own channels:

```
arrakis-server mock my_channels.toml
```

A minimal channel file:

``` toml
["common"]
publisher = "MY_PUBLISHER"
sample_rate = 256
data_type = "float32"
stride = 62_500_000
max_latency = 1_000_000_000

["MY:CHANNEL-NAME"]
func = "3*t + cos(t)"
```

`func` accepts any [SymPy](https://www.sympy.org/) expression in `t` (GPS
seconds) to generate deterministic waveforms.

### Run as an information server

An information server holds no data of its own; it routes client requests
to other Arrakis endpoints based on a scope map:

```
arrakis-server --scope-map scope.yaml
```

The scope map lists each downstream endpoint along with the scopes and
retention windows it serves. See the
[Scope Maps](https://ngdd.docs.ligo.org/arrakis-server/user/scope-maps/)
guide for the file format, and
[Multi-Backend Deployments](https://ngdd.docs.ligo.org/arrakis-server/user/multi-backend/)
for composing live and historical backends.

### Write a backend

Backends plug in via the `arrakis-server-backend` entry-point group. A
minimal backend implements the `ServerBackend` protocol and registers in
its package's `pyproject.toml`:

``` toml
[project.entry-points.arrakis-server-backend]
mybackend = "my_package.backend:MyBackend"
```

See [Writing a Backend](https://ngdd.docs.ligo.org/arrakis-server/background/writing-a-backend/)
for the full interface and a complete example.
