pict-rs: add initial module

4 files changed, 301 insertions, 0 deletions

diff --git a/nixos/modules/module-list.nix b/nixos/modules/module-list.nix
index 4f48ee5a80a..bff7b83ea71 100644
--- a/nixos/modules/module-list.nix
+++ b/nixos/modules/module-list.nix
@@ -991,6 +991,7 @@
   ./services/web-apps/nextcloud.nix
   ./services/web-apps/nexus.nix
   ./services/web-apps/node-red.nix
+  ./services/web-apps/pict-rs.nix
   ./services/web-apps/plantuml-server.nix
   ./services/web-apps/plausible.nix
   ./services/web-apps/pgpkeyserver-lite.nix
diff --git a/nixos/modules/services/web-apps/pict-rs.md b/nixos/modules/services/web-apps/pict-rs.md
new file mode 100644
index 00000000000..4b622049909
--- /dev/null
+++ b/nixos/modules/services/web-apps/pict-rs.md
@@ -0,0 +1,88 @@
+# Pict-rs {#module-services-pict-rs}
+
+pict-rs is a  a simple image hosting service.
+
+## Quickstart {#module-services-pict-rs-quickstart}
+
+the minimum to start pict-rs is
+
+```nix
+services.pict-rs.enable = true;
+```
+
+this will start the http server on port 8080 by default.
+
+## Usage {#module-services-pict-rs-usage}
+
+pict-rs offers the following endpoints:
+- `POST /image` for uploading an image. Uploaded content must be valid multipart/form-data with an
+    image array located within the `images[]` key
+
+    This endpoint returns the following JSON structure on success with a 201 Created status
+    ```json
+    {
+        "files": [
+            {
+                "delete_token": "JFvFhqJA98",
+                "file": "lkWZDRvugm.jpg"
+            },
+            {
+                "delete_token": "kAYy9nk2WK",
+                "file": "8qFS0QooAn.jpg"
+            },
+            {
+                "delete_token": "OxRpM3sf0Y",
+                "file": "1hJaYfGE01.jpg"
+            }
+        ],
+        "msg": "ok"
+    }
+    ```
+- `GET /image/download?url=...` Download an image from a remote server, returning the same JSON
+    payload as the `POST` endpoint
+- `GET /image/original/{file}` for getting a full-resolution image. `file` here is the `file` key from the
+    `/image` endpoint's JSON
+- `GET /image/details/original/{file}` for getting the details of a full-resolution image.
+    The returned JSON is structured like so:
+    ```json
+    {
+        "width": 800,
+        "height": 537,
+        "content_type": "image/webp",
+        "created_at": [
+            2020,
+            345,
+            67376,
+            394363487
+        ]
+    }
+    ```
+- `GET /image/process.{ext}?src={file}&...` get a file with transformations applied.
+    existing transformations include
+    - `identity=true`: apply no changes
+    - `blur={float}`: apply a gaussian blur to the file
+    - `thumbnail={int}`: produce a thumbnail of the image fitting inside an `{int}` by `{int}`
+        square using raw pixel sampling
+    - `resize={int}`: produce a thumbnail of the image fitting inside an `{int}` by `{int}` square
+        using a Lanczos2 filter. This is slower than sampling but looks a bit better in some cases
+    - `crop={int-w}x{int-h}`: produce a cropped version of the image with an `{int-w}` by `{int-h}`
+        aspect ratio. The resulting crop will be centered on the image. Either the width or height
+        of the image will remain full-size, depending on the image's aspect ratio and the requested
+        aspect ratio. For example, a 1600x900 image cropped with a 1x1 aspect ratio will become 900x900. A
+        1600x1100 image cropped with a 16x9 aspect ratio will become 1600x900.
+
+    Supported `ext` file extensions include `png`, `jpg`, and `webp`
+
+    An example of usage could be
+    ```
+    GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0
+    ```
+    which would create a 256x256px JPEG thumbnail and blur it
+- `GET /image/details/process.{ext}?src={file}&...` for getting the details of a processed image.
+    The returned JSON is the same format as listed for the full-resolution details endpoint.
+- `DELETE /image/delete/{delete_token}/{file}` or `GET /image/delete/{delete_token}/{file}` to
+    delete a file, where `delete_token` and `file` are from the `/image` endpoint's JSON
+
+## Missing {#module-services-pict-rs-missing}
+
+- Configuring the secure-api-key is not included yet. The envisioned basic use case is consumption on localhost by other services without exposing the service to the internet.
diff --git a/nixos/modules/services/web-apps/pict-rs.nix b/nixos/modules/services/web-apps/pict-rs.nix
new file mode 100644
index 00000000000..e1847fbd531
--- /dev/null
+++ b/nixos/modules/services/web-apps/pict-rs.nix
@@ -0,0 +1,50 @@
+{ lib, pkgs, config, ... }:
+with lib;
+let
+  cfg = config.services.pict-rs;
+in
+{
+  meta.maintainers = with maintainers; [ happysalada ];
+  # Don't edit the docbook xml directly, edit the md and generate it:
+  # `pandoc pict-rs.md -t docbook --top-level-division=chapter --extract-media=media -f markdown+smart > pict-rs.xml`
+  meta.doc = ./pict-rs.xml;
+
+  options.services.pict-rs = {
+    enable = mkEnableOption "pict-rs server";
+    dataDir = mkOption {
+      type = types.path;
+      default = "/var/lib/pict-rs";
+      description = ''
+        The directory where to store the uploaded images.
+      '';
+    };
+    address = mkOption {
+      type = types.str;
+      default = "127.0.0.1";
+      description = ''
+        The IPv4 address to deploy the service to.
+      '';
+    };
+    port = mkOption {
+      type = types.port;
+      default = 8080;
+      description = ''
+        The port which to bind the service to.
+      '';
+    };
+  };
+  config = lib.mkIf cfg.enable {
+    systemd.services.pict-rs = {
+      environment = {
+        PICTRS_PATH = cfg.dataDir;
+        PICTRS_ADDR = "${cfg.address}:${toString cfg.port}";
+      };
+      wantedBy = [ "multi-user.target" ];
+      serviceConfig = {
+        DynamicUser = true;
+        StateDirectory = "pict-rs";
+        ExecStart = "${pkgs.pict-rs}/bin/pict-rs";
+      };
+    };
+  };
+}
diff --git a/nixos/modules/services/web-apps/pict-rs.xml b/nixos/modules/services/web-apps/pict-rs.xml
new file mode 100644
index 00000000000..bf129f5cc2a
--- /dev/null
+++ b/nixos/modules/services/web-apps/pict-rs.xml
@@ -0,0 +1,162 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-pict-rs">
+  <title>Pict-rs</title>
+  <para>
+    pict-rs is a a simple image hosting service.
+  </para>
+  <section xml:id="module-services-pict-rs-quickstart">
+    <title>Quickstart</title>
+    <para>
+      the minimum to start pict-rs is
+    </para>
+    <programlisting language="bash">
+services.pict-rs.enable = true;
+</programlisting>
+    <para>
+      this will start the http server on port 8080 by default.
+    </para>
+  </section>
+  <section xml:id="module-services-pict-rs-usage">
+    <title>Usage</title>
+    <para>
+      pict-rs offers the following endpoints: -
+      <literal>POST /image</literal> for uploading an image. Uploaded
+      content must be valid multipart/form-data with an image array
+      located within the <literal>images[]</literal> key
+    </para>
+    <programlisting>
+This endpoint returns the following JSON structure on success with a 201 Created status
+```json
+{
+    &quot;files&quot;: [
+        {
+            &quot;delete_token&quot;: &quot;JFvFhqJA98&quot;,
+            &quot;file&quot;: &quot;lkWZDRvugm.jpg&quot;
+        },
+        {
+            &quot;delete_token&quot;: &quot;kAYy9nk2WK&quot;,
+            &quot;file&quot;: &quot;8qFS0QooAn.jpg&quot;
+        },
+        {
+            &quot;delete_token&quot;: &quot;OxRpM3sf0Y&quot;,
+            &quot;file&quot;: &quot;1hJaYfGE01.jpg&quot;
+        }
+    ],
+    &quot;msg&quot;: &quot;ok&quot;
+}
+```
+</programlisting>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <literal>GET /image/download?url=...</literal> Download an
+          image from a remote server, returning the same JSON payload as
+          the <literal>POST</literal> endpoint
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>GET /image/original/{file}</literal> for getting a
+          full-resolution image. <literal>file</literal> here is the
+          <literal>file</literal> key from the <literal>/image</literal>
+          endpoint’s JSON
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>GET /image/details/original/{file}</literal> for
+          getting the details of a full-resolution image. The returned
+          JSON is structured like so:
+          <literal>json     {         &quot;width&quot;: 800,         &quot;height&quot;: 537,         &quot;content_type&quot;: &quot;image/webp&quot;,         &quot;created_at&quot;: [             2020,             345,             67376,             394363487         ]     }</literal>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>GET /image/process.{ext}?src={file}&amp;...</literal>
+          get a file with transformations applied. existing
+          transformations include
+        </para>
+        <itemizedlist spacing="compact">
+          <listitem>
+            <para>
+              <literal>identity=true</literal>: apply no changes
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>blur={float}</literal>: apply a gaussian blur to
+              the file
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>thumbnail={int}</literal>: produce a thumbnail of
+              the image fitting inside an <literal>{int}</literal> by
+              <literal>{int}</literal> square using raw pixel sampling
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>resize={int}</literal>: produce a thumbnail of
+              the image fitting inside an <literal>{int}</literal> by
+              <literal>{int}</literal> square using a Lanczos2 filter.
+              This is slower than sampling but looks a bit better in
+              some cases
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <literal>crop={int-w}x{int-h}</literal>: produce a cropped
+              version of the image with an <literal>{int-w}</literal> by
+              <literal>{int-h}</literal> aspect ratio. The resulting
+              crop will be centered on the image. Either the width or
+              height of the image will remain full-size, depending on
+              the image’s aspect ratio and the requested aspect ratio.
+              For example, a 1600x900 image cropped with a 1x1 aspect
+              ratio will become 900x900. A 1600x1100 image cropped with
+              a 16x9 aspect ratio will become 1600x900.
+            </para>
+          </listitem>
+        </itemizedlist>
+        <para>
+          Supported <literal>ext</literal> file extensions include
+          <literal>png</literal>, <literal>jpg</literal>, and
+          <literal>webp</literal>
+        </para>
+        <para>
+          An example of usage could be
+          <literal>GET /image/process.jpg?src=asdf.png&amp;thumbnail=256&amp;blur=3.0</literal>
+          which would create a 256x256px JPEG thumbnail and blur it
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>GET /image/details/process.{ext}?src={file}&amp;...</literal>
+          for getting the details of a processed image. The returned
+          JSON is the same format as listed for the full-resolution
+          details endpoint.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>DELETE /image/delete/{delete_token}/{file}</literal>
+          or <literal>GET /image/delete/{delete_token}/{file}</literal>
+          to delete a file, where <literal>delete_token</literal> and
+          <literal>file</literal> are from the <literal>/image</literal>
+          endpoint’s JSON
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+  <section xml:id="module-services-pict-rs-missing">
+    <title>Missing</title>
+    <itemizedlist spacing="compact">
+      <listitem>
+        <para>
+          Configuring the secure-api-key is not included yet. The
+          envisioned basic use case is consumption on localhost by other
+          services without exposing the service to the internet.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+</chapter>