xq-api(8) Manual Page

Name

xq-api - serve XBPS repodata over HTTP

Synopsis

xq-api [OPTIONS] [--] <REPODATA…​>

Description

xq-api serves XBPS repodata over HTTP, formatting its responses as JSON. It loads repodata into memory prior to serving it.

Options

-h, -help

Print all CLI flags. This includes glog flags not described below that are primarily used for debugging and log rotation.

-net={network}

The type of network address to listen on. May be one of unix (Unix domain socket), tcp, tcp4 (IPv4 only), or tcp6 (IPv6 only). Defaults to tcp.

-listen={addr}

The address to listen on. If -net is unix, this is a path to the Unix domain socket to create. Defaults to 127.0.0.1:8197, regardless of what -net is.

-max-queries={n}

The maximum number of query requests that can run in parallel. If more than n query requests are made in parallel, they will block until others complete. Defaults to 16.

-reload-every={duration}

Reload repository data every duration. If the duration is zero or a negative interval, automatic reloading is disabled. By default, automatic reloading is disabled.

-log-access={t|f}

Whether to emit access logs. Requests that get a 404, 304, or 0 response are not logged. If passed without a value, t is assumed. Defaults to f.

-logtostderr={t|f}

Whether to log to standard error or files. If f, logs are written to log_dir (below). Defaults to t.

-alsologtostderr={t|f}

Whether to log to stderr in addition to files, if logtostderr is f. Defaults to f.

-log_dir={logdir}

The directory to write log files to. Only used if logtostderr is f. If dir cannot be used, it will fall back to the temporary directory. Defaults to the temporary directory.

In addition, there are other common glog flags that are detailed in usage output.

Signals

xq-api responds to HUP by reloading the repodata it was given on the command line.

After the server has been started, it responds to TERM and INT signals by attempting to gracefully shut down the server.

Repodata

When passing repodata to xq-api, it expects to receive either a directory containing one or more repodata files or an individual repodata file. For example, to serve repodata from the current machine, one can start xq-api with the following (which will match the vast majority of repositories, if any are synced):

$ xq-api /var/db/xbps/http*/*-repodata
loading repodata...
loading /var/db/xbps/http___alpha_de_repo_voidlinux_org_current/x86_64-repodata
...

Alternatively, you can pass directories:

$ xq-api /var/db/xbps/http*
loading repodata...
loading /var/db/xbps/http___alpha_de_repo_voidlinux_org_current/x86_64-repodata
...

Symbolic links are not followed when walking a directory to find repodata. If you need this, please open an issue on https://github.com/nilium/xq-api.

Responses

All responses from xq-api, with the exception of redirects, yield JSON output of the form {"data": <RequestedThing>}, where RequestedThing is either an object or an array.

Unexpected or invalid paths respond with 404 and an empty {} object.

Paths

The following paths are available in xq-api.

Note	All example responses are pretty-printed for convenience. xq-api does not pretty-print JSON.

/v1/archs

Responds with an array of strings identifying valid architectures for use with other paths.

Example

{
  "data": [
    "aarch64",
    "aarch64-musl",
    "armv6l",
    "armv6l-musl",
    "armv7l",
    "armv7l-musl",
    "i686",
    "i686-musl",
    "x86_64",
    "x86_64-musl"
  ]
}

/v1/packages/{arch}

Responds with an array of strings identifying valid packages for arch.

The array is lexicographically ordered case-sensitively.

Parameters

arch

An architecture served by xq-api. Valid architectures are returned from /v1/archs.

Example

{
  "data": [
    "0ad",
    "0ad-32bit",
    "0ad-data",
    "2048-qt",
    "2bwm",
    "... EXAMPLE ELLIPSIZED ...",
    "zzuf",
    "zzuf-32bit"
  ]
}

/v1/packages/{arch}/{package}

Responds with an object describing the package from repodata.

This is intended to be the same as what you can see by looking up the package with xbps-query(1) with some alterations:

• pkgver is split into name, version, and revision JSON fields. pkgver itself is not served.

• Field names with hyphens in xbps-query have underscores in xq-api (such as filename_sha256). This is for convenience when using these fields in languages like Javascript.

• Timestamps are formated in RFC 3339. This is, again, for convenience in working with other languages.

Parameters

arch

An architecture served by xq-api. Valid architectures are returned from /v1/archs.

package

A package under arch. Valid package names are retruend from /v1/packages/{arch}.

Data Fields

Any field that is empty, zero, or false is omitted from the response as it is the default value for that field.

In the list below, []string is an array of strings.

• name: string

• version: string

• revision: integer

• repository: string

• architecture: string

• build_date: string (RFC 3339 timestamp)

• build_options: string

• filename_sha256: string

• filename_size: integer

• homepage: string (url)

• installed_size: integer

• license: string

• maintainer: string

• short_desc: string

• preserve: bool (only set if true)

• source_revisions: string

• run_depends: []string

• shlib_requires: []string

• shlib_provides: []string

• conflicts: []string

• reverts: []string

• replaces: []string

• alternatives: map[string][]string (a map of strings to arrays of strings, such as { "key": ["values"] })

• conf_files: []string

Example

{
  "data": {
    "name": "retrap",
    "version": "1.0.1",
    "revision": 2,
    "repository": "current",
    "architecture": "x86_64",
    "build_date": "2019-01-10T09:03:00Z",
    "filename_sha256": "35eb56b97d20b04afe6bb40f471b849e4f4022d999bbbc0e4b48fc78e68ffe14",
    "filename_size": 1065888,
    "homepage": "https://github.com/nilium/retrap",
    "installed_size": 2365759,
    "license": "BSD-2-Clause",
    "maintainer": "Noel Cower <ncower@gmail.com>",
    "short_desc": "Remap signals and forward them to a child process",
    "run_depends": [
      "glibc>=2.28_1"
    ],
    "shlib_requires": [
      "libpthread.so.0",
      "libc.so.6"
    ]
  }
}

/v1/query/{arch}?q={query}

Responds with an array containing packages under arch that match the query. The resulting package objects contain only a subset of their full fields.

Parameters

arch

An architecture served by xq-api. Valid architectures are returned from /v1/archs.

query

A query string to filter results by. Only pkgver (the combination of name, version, and revison) and short_desc are searched. If empty, all packages are returned.

Data Fields

• name: string

• version: string

• revision: integer

• filename_size: integer (bytes)

• repository: string (omitted if empty)

• short_desc: string (omitted if empty)

Example

{
  "data": [
    {
      "name": "retrap",
      "version": "1.0.1",
      "revision": 2,
      "filename_size": 1065888,
      "repository": "current",
      "short_desc": "Remap signals and forward them to a child process"
    }
  ]
}

Building xq-api

To build xq-api, you can use make:

$ make xq-api

And to build the manpage:

$ make xq-api.8

Or, to build both:

$ make

Otherwise, to build xq-api with the Go tool from within the source tree:

$ go build go.spiff.io/xq-api

Reporting Issues

If you encounter a bug in xq-api, or want to request a feature or something else, please open an issue on the project website if one doesn’t already exist: https://github.com/nilium/xq-api.

You can also submit pull requests through the project site.