Lithium/README.md

# Lithium

Micro-service for file storage and processing written in Go.

## Features

- Image processing pipelines for various transformations
- Web API for storing & retrieving files

## Requirements

- [Go 1.17+](https://go.dev/)
- [_Docker_](https://docs.docker.com/) (optional)

## Setup

#### 1. Clone repository

```shell
git clone git@gogs.informatik.hs-fulda.de:FabianVowie/Lithium.git
```

#### 2. Pull dependencies

```shell
go get
```

#### 3. Build & start application

```shell
go run .
```

**Run using [Docker](https://docs.docker.com/) container**

```shell
docker run --rm -p 8000:8000 -v "$PWD":/usr/src/lithium -w /usr/src/lithium golang:1.17 go run .
```

## Testing

```shell
go test ./...
```

### Run tests in verbose logging mode

```shell
go test ./... -v
```

### Run tests in [Docker](https://docs.docker.com/) container

```shell
docker run --rm -v "$PWD":/usr/src/lithium -w /usr/src/lithium golang:1.17 go test ./...
```

## Configuration

Config options can be adjusted via the [`settings.json`](settings.json) file in the root directory.

```json
{
  "endpoint": "0.0.0.0:8000",
  "token": "changeme",
  "rate_limiter": {
    "requests_per_minute": 20,
    "allowed_burst": 5
  },
  "storage_provider": {
    "type": 0,
    "base_path": "assets"
  }
}
```

## Rate Limiting

By default, the rate limiting takes place on a per-route basis. When the limit for a specific route is hit, the response will return a status code `429: Too Many Requests`.

| Headers               | Explanation                      |
| --------------------- | -------------------------------- |
| X-Ratelimit-Limit     | Allowed requests per minute      |
| X-Ratelimit-Remaining | Remaining requests               |
| X-Ratelimit-Reset     | Seconds until requests replenish |

## API

### `GET` `/`

Show application information.

**Required headers**:

```shell
Authorization: Bearer <Token>
```

**Example response**:

```json
{
  "name": "Lithium",
  "version": "0.1.0"
}
```

### `GET` `/{pipeline}`

Show pipeline information.

**Required headers**:

```shell
Authorization: Bearer <Token>
```

**Example response**:

```json
{
  "name": "example pipeline",
  "slug": "example",
  "type": 0,
  "remove_metadata": false,
  "steps": [
    {
      "name": "resize image",
      "type": 0,
      "options": {
        "width": 1280,
        "height": 720,
        "upscale": false
      }
    }
  ],
  "output": {
    "format": "jpg",
    "quality": 90
  }
}
```

## Pipelines

The project uses a pipeline system defined by [JSON](https://en.wikipedia.org/wiki/JSON) files located in the [config](config) folder.
Take a look at the [example pipeline configuration file](config/example.json).

Available pipeline `type`s: `0` (Image), `1` (Video)

```json
{
  "name": "example pipeline",
  "slug": "example",
  "type": 0,
  "removeMetadata": false,
  "steps": [],
  "output": {}
}
```

### Images pipeline

The image pipeline offers the following additional output options.

Available `format` types: `jpg` (or `jpeg`), `png`, `gif`, `tif` (or `tiff`) and `bmp`  
The `quality` field can contain any integer between 1 and 100.

```json
{
  "output": {
    "format": "jpg",
    "quality": 90
  }
}
```

### Available pipeline steps

Each pipeline step consists of an optional `name`, a predefined `type` and configurable `options`.
See the available options below for more information.

```json
{
  "name": "step name",
  "type": 0,
  "options": {}
}
```

#### Resizing images

Resize an image by a given `width` and `height`.

**Step definition**:

```json
{
  "type": 0,
  "options": {
    "width": 1280,
    "height": 720
  }
}
```

#### Rotating images

Rotate an image with a given `angle` in degrees.

**Step definition**:

```json
{
  "type": 1,
  "options": {
    "angle": 90.0
  }
}
```

#### Flipping images

Flip an image with a given direction.
Allowed values for the `direction` option are `"h"` (horizontal), `"v"` (vertical)

**Step definition**:

```json
{
  "type": 2,
  "options": {
    "direction": "h"
  }
}
```

#### Grayscale

Convert the colorspace of an image into grayscale.

**Step definition**:

```json
{
  "type": 3
}
```

#### Fit

Scales down the image to fit the specified maximum width and height.

**Step definition**:

```json
{
  "type": 4,
  "options": {
    "height": 300,
    "width": 200
  }
}
```

#### Invert

Invert image colors.

**Step definition**:

```json
{
  "type": 5
}
```

#### Blur

Blur image using Gaussian functions.

**Step definition**:

```json
{
  "type": 6,
  "options": {
    "sigma": 50.0
  }
}
```

## Authors

- [Fabian Vowie](https://gogs.informatik.hs-fulda.de/FabianVowie)
- [Roman Zipp](https://gogs.informatik.hs-fulda.de/roman.zipp)