Custom Repositories
Applicable to
3.x

Beacon provides the facilities to create custom service repositories and provide them to any number of users via various distribution methods.

Repository Compiler
We currently do not provide a standalone version of the Beacon repository compiler thus requiring some experience with Java/Kotlin development practices. The compiler is provided as part of the repository-compiler module and may be accessed via any standard Maven compatible development environment.

Repository Format

Repositories are defined using an intermediate schema represented using JSON. In general, they are structured as follows: 

{
  "displayName": "My Repository",
  "revision": 1,
  "services": [
    {
      "id": "game+custom://my-game-uri",
      "title": "Custom Game",
      "icon": "https://example.org/icon.png",
      "category": "GAME",
      "ports": [
        {
          "protocol": "UDP",
          "number": "19132"
        }
      ]
    }
  ]
}

The following repository-level parameters are provided:

  • displayName - Human readable name for the repository (currently unused)
  • revision - Numerical file version (currently unused)
  • services - Listing of known services

Services are additionally structured as follows:

  • id - Globally unique identifier for this service
  • title - Human readable name for the service
  • icon - HTTP(S) URL to an icon (optional)
  • category - One of either GAME or TOOL
  • ports - Listing of ports to be exposed

Port numbers expose the following parameters:

  • protocol - One of either TCP or UDP
  • number - A port number within the range of 1-65,535

Considerations

Service IDs

Service identifiers are globally unique (meaning no two services may share the same identifier as one of the two services would otherwise be discarded by the application).

Any valid URI may be used as a service identifier thus shifting the burden of designating a sensible identifier pattern to the repository provider. Some examples can be found within the stock repository located within the repositories directory in the source code.

Distribution Schemes

Beacon recognizes a set of distribution providers via which the application will fetch custom repositories. The following implementations are currently available:

File (Testing only)

Example: file:///home/user/test/myrepo.dat

The file implementation is provided for testing purposes only (e.g. to load compiled repositories before publishing them. File repositories are formatted in accordance with the file URI protocol and are thus somewhat system dependent.

For *NIX users
Please note that relative paths are not supported on *NIX based operating system (e.g. Linux as well as actual UNIX certified implementations). Absolute paths must be specified when using this provider.

HTTP(S)

Example: https://example.org/myrepo.dat

The HTTP implementation simply downloads a given repository from a standard HTTP(S) enabled server. The server is expected to reply with a 200 OK status code. The file content type is simply ignored.

GitHub

Example: github://owner/repo#myrepo.dat

The GitHub implementation locates the latest release within a given GitHub repository which includes the specified repository file. This implementation is used by the stock repository.