distromatic/README.md

distromatic project for the *openmamba Linux* distribution
==================================================
This project provides tools that have been developed by the maintainers of the *openmamba Linux* distribution in order to maintain, monitor and provide user interfaces for RPM based package repositories.

# `distromatic` tool
`distromatic` is a command line tool which scans repositories with `rpm` and `srpm` packages or `repodata` folders containing metadata files and provides output files as *sqlite* databases, plaintext and html with detailed information on repositories and packages.

The created files are used for distribution maintainance purposes and to provide informative interfaces to end users.

# `distroquery` tool
`distroquery` is a command line tool intended to be used as a `CGI` backend for the web. It provides **API** interfaces intended to be used by *web frontends* and *development instruments* in order to provide dynamic information on distribution repositories and packages.

## `distroquery` API services
The newest distroquery API interface is currently available from this prefix: [https://push.openmamba.org/openmamba/distroquery/api/v1](https://push.openmamba.org/openmamba/distroquery/api/v1).

### Repositories list `/api/v1/repositories`
Returns a list of all available repositories.

#### Example
[https://push.openmamba.org/openmamba/distroquery/api/v1/repositories](https://push.openmamba.org/openmamba/distroquery/api/v1/repositories)

*Request with cURL*:
```
curl "https://push.openmamba.org/openmamba/distroquery/api/v1/repositories"
```

*Response*:
```
[
  {
    "tag": "base",
    "archs": [
      "x86_64",
      "aarch64",
      "i586"
    ],
    "description": "openmamba base repository [rolling]",
    "parents": []
  },
  {
    "tag": "devel-makedist",
    "archs": [
      "x86_64",
      "aarch64",
      "i586"
    ],
    "description": "openmamba staging packages repository [unstable]",
    "parents": [
      "base"
    ]
  },
%----------OUTPUT CUT----------%
]
```

### Repository packages `/api/v1/repository`
Returns a list of packages available in a repository.

#### Query string parameters
* `q=term`: filters the results with name and description matching the given term;
* `per_page=n`: returns `n` results (default is `100`);
* `page=n`: shows the `n`th page of results

#### Example
[https://push.openmamba.org/openmamba/distroquery/api/v1/repository/base?page=1&per_page=10](https://push.openmamba.org/openmamba/distroquery/api/v1/repository/base?page=1&per_page=10)

*Request with cURL*:
```
curl "https://push.openmamba.org/openmamba/distroquery/api/v1/repository/base?page=1&per_page=10" 
```

*Response*:
```
{
  "query": {
    "repository": "base",
    "per_page": 10,
    "page": 1,
    "q": "",
    "total": 42413,
    "pages": 4242,
    "from": 1,
    "to": 10
  },
  "packages": [
    {
      "name": "54321",
      "arch": "src",
      "version": "1.0.2001.11.16",
      "release": "4mamba",
      "summary": "54321 is five games in four-, three-, or two-dimensions for one player.",
      "buildtime": "2021-02-27T19:17:12Z"
    },
%----------OUTPUT CUT----------%
    {
      "name": "a2ps-debug",
      "arch": "i586",
      "version": "4.15.6",
      "release": "1mamba",
      "summary": "Debug information for package a2ps",
      "buildtime": "2024-03-15T19:37:03Z"
    }
  ]
}
```

### Source package details `/api/v1/package`
Returns the details for a source or binary package.

#### URI arguments
For source packages the `URI` is in the form:

`/api/v1/repository/package`

For binary packages:

`/api/v1/repository/package/arch`

Where:

* **repository**: is the name of the repository containing the package;
* **package**: is the name of the source or binary package to query for;
* **arch**: is the architecture of the binary package to query for.

#### Source package example
[https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash](https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash)

`Request with cURL`:
```
curl https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash
```

`Response`:
```
{
  "id": 204,
  "name": "bash",
  "summary": "The GNU Bourne Again shell (bash)",
  "epoch": "0",
  "version": "5.2.p32",
  "release": "1mamba",
  "description": "Bash (Bourne Again shell) is the shell, or command language interpreter, that will appear in the GNU operating system.\nBash is an sh-compatible shell that incorporates useful features from the Korn shell (ksh) and C shell (csh).\nIt is intended to conform to the IEEE POSIX P1003.2/ISO 9945.2 Shell and Tools standard.\nIt offers functional improvements over sh for both programming and interactive use.\nIn addition, most sh scripts can be run by Bash without modification.\n\nThe improvements offered by BASH include:\n* Command line editing\n* Unlimited size command history\n* Job Control\n* Shell Functions and Aliases\n* Indexed arrays of unlimited size\n* Integer arithmetic in any base from two to sixty-four",
  "group": "Applications/Shells",
  "license": "GPL",
  "url": "http://www.gnu.org/software/bash/bash.html",
  "size": 11028405,
  "maintainer": "silvan",
  "buildtime": "2024-08-01T05:11:43Z",
  "download_url": "/download.html?file=/pub/openmamba/base/SRPMS.base/bash-5.2.p32-1mamba.src.rpm",
  "source_url": "https://src.openmamba.org/rpms/bash",
  "buildrequires": [
    {
      "name": "bison",
      "flags": "",
      "version": "",
      "providers": {
        "archs": {
          "aarch64": [
            {
              "repository": "base",
              "name": "bison",
              "flags": "=",
              "version": "0:3.8.2-1mamba"
            }
          ],
          "i586": [
            {
              "repository": "base",
              "name": "bison",
              "flags": "=",
              "version": "0:3.8.2-1mamba"
            }
          ],
          "x86_64": [
            {
              "repository": "base",
              "name": "bison",
              "flags": "=",
              "version": "0:3.8.2-1mamba"
            }
          ]
        }
      }
    },
%----------OUTPUT CUT----------%
  ],
  "children": {
    "archs": {
      "x86_64": [
        {
          "name": "bash"
        },
        {
          "name": "bash-debug"
        },
        {
          "name": "bash-devel"
        },
        {
          "name": "bash-doc"
        }
      ],
      "aarch64": [
        {
          "name": "bash"
        },
        {
          "name": "bash-debug"
        },
        {
          "name": "bash-devel"
        },
        {
          "name": "bash-doc"
        }
      ],
      "i586": [
        {
          "name": "bash"
        },
        {
          "name": "bash-debug"
        },
        {
          "name": "bash-devel"
        },
        {
          "name": "bash-doc"
        }
      ]
    }
  },
  "changelog": [
    {
      "date": "2024-08-01T12:00:00Z",
      "packager": "Automatic Build System <autodist@openmamba.org>",
      "release": "5.2.p32-1mamba",
      "text": "- automatic version update by autodist"
    },
%----------OUTPUT CUT----------%
  ]
}
```

#### Binary package example
[https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash/x86_64](https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash/x86_64)

*Request with cURL*:
```
curl https://push.openmamba.org/openmamba/distroquery/api/v1/package/base/bash/x86_64
```

*Response*:
```
{
  "id": 368,
  "name": "bash",
  "summary": "The GNU Bourne Again shell (bash)",
  "epoch": "0",
  "version": "5.2.p32",
  "release": "1mamba",
  "description": "Bash (Bourne Again shell) is the shell, or command language interpreter, that will appear in the GNU operating system.\nBash is an sh-compatible shell that incorporates useful features from the Korn shell (ksh) and C shell (csh).\nIt is intended to conform to the IEEE POSIX P1003.2/ISO 9945.2 Shell and Tools standard.\nIt offers functional improvements over sh for both programming and interactive use.\nIn addition, most sh scripts can be run by Bash without modification.\n\nThe improvements offered by BASH include:\n* Command line editing\n* Unlimited size command history\n* Job Control\n* Shell Functions and Aliases\n* Indexed arrays of unlimited size\n* Integer arithmetic in any base from two to sixty-four",
  "group": "Applications/Shells",
  "arch": "x86_64",
  "size": 2530934,
  "source": {
    "id": 204,
    "name": "bash",
    "summary": "The GNU Bourne Again shell (bash)",
    "epoch": "0",
    "version": "5.2.p32",
    "release": "1mamba",
    "description": "Bash (Bourne Again shell) is the shell, or command language interpreter, that will appear in the GNU operating system.\nBash is an sh-compatible shell that incorporates useful features from the Korn shell (ksh) and C shell (csh).\nIt is intended to conform to the IEEE POSIX P1003.2/ISO 9945.2 Shell and Tools standard.\nIt offers functional improvements over sh for both programming and interactive use.\nIn addition, most sh scripts can be run by Bash without modification.\n\nThe improvements offered by BASH include:\n* Command line editing\n* Unlimited size command history\n* Job Control\n* Shell Functions and Aliases\n* Indexed arrays of unlimited size\n* Integer arithmetic in any base from two to sixty-four",
    "group": "Applications/Shells",
    "license": "GPL",
    "url": "http://www.gnu.org/software/bash/bash.html",
    "size": 11028405,
    "maintainer": "silvan",
    "buildtime": "2024-08-01T05:11:43Z",
    "download_url": "/download.html?file=/pub/openmamba/base/SRPMS.base/bash-5.2.p32-1mamba.src.rpm",
    "source_url": "https://src.openmamba.org/rpms/bash"
  },
  "download_url": "/download.html?file=/pub/openmamba/base/RPMS.x86_64/bash-5.2.p32-1mamba.x86_64.rpm",
  "brothers": [
    "bash-debug",
    "bash-devel",
    "bash-doc"
  ],
  "obsoletes": [],
  "provides": [
    {
      "name": "/bin/sh",
      "flags": "",
      "version": ""
    },
    {
      "name": "/usr/bin/bash",
      "flags": "",
      "version": ""
    },
    {
      "name": "/usr/bin/sh",
      "flags": "",
      "version": ""
    },
    {
      "name": "bash",
      "flags": "=",
      "version": "0:5.2.p32-1mamba"
    },
    {
      "name": "bash(x86-64)",
      "flags": "=",
      "version": "0:5.2.p32-1mamba"
    }
  ],
  "requires": [
    {
      "name": "/sbin/install-info",
      "flags": "",
      "version": "",
      "providers": [
        {
          "repository": "base",
          "name": "texinfo",
          "flags": "",
          "version": ""
        }
      ]
    },
%----------OUTPUT CUT----------%
  ],
  "files": [
    {
      "path": "/bin/bash"
    },
%----------OUTPUT CUT----------%
    {
      "path": "/usr/share/man/man1/builtins.1.gz"
    }
  ]
}
```

### Binary package files list `/api/v1/package_files`
Returns the list of files provided with a binary package.

Example: [https://push.openmamba.org/openmamba/distroquery/api/v1/package_files/base/bash/x86_64](https://push.openmamba.org/openmamba/distroquery/api/v1/package_files/base/bash/x86_64)

### Providers for requirement `/api/v1/providers`
Returns a list of packages with match with a requirement.

Example: [https://push.openmamba.org/openmamba/distroquery/api/v1/providers/base/glibc/>=/2.40](https://push.openmamba.org/openmamba/distroquery/api/v1/providers/base/glibc/>=/2.40)

### Providers for file `/api/v1/file_providers`
Returns a list of packages which provide a file.

Example: [https://push.openmamba.org/openmamba/distroquery/api/v1/file_providers/base/%2Fbin%2Fbash/x86_64](https://push.openmamba.org/openmamba/distroquery/api/v1/file_providers/base/%2Fbin%2Fbash/x86_64)

### Repository problems `/api/v1/problems`
Returns a list of problems which affects the packages of a repository.

Example: [https://push.openmamba.org/openmamba/distroquery/api/v1/problems/base](https://push.openmamba.org/openmamba/distroquery/api/v1/problems/base)