Extending Building Registry Entries

Building Registry Entries

Prev: Testing Lua Plugins | Up: Extending ReqPack | Next: Building rqp Packages and Repositories

The registry tells ReqPack where plugin wrappers come from and what trust metadata they carry. It is distribution and trust layer, not plugin implementation layer.

You can define plugin sources in two ways:

1. local Lua source maps such as registry.lua or config.registry.sources,
2. Git-backed registry JSON files tracked in a registry repository.

Built-in rqp plugin does not come from registry. Registry primarily describes wrapper-style plugins and aliases.

Registry Layers

ReqPack merges registry sources in this order:

1. downloader plugin sources from downloader.pluginSources,
2. config.registry.sources,
3. registry.lua under registry.databasePath,
4. config.registry.overlayPath.

Later layers win. That makes overlays useful for local overrides during development.

Local registry.lua Format

When registry.databasePath points to a directory, ReqPack reads <databasePath>/registry.lua.

Example:

return {
  sources = {
    dnf = "https://example.test/dnf.lua",
    maven = {
      source = "central-maven",
      alias = true,
    },
  },
}

Each source entry can be a simple string or a table.

• string form means direct source reference for plugin payload
• table form is used when you need aliases or extra trust metadata
• when alias = true, source should be canonical plugin name, not URL

Useful fields:

• source
• alias
• description
• role
• capabilities
• ecosystemScopes
• writeScopes
• networkScopes
• privilegeLevel
• scriptSha256
• bootstrapSha256

Git-backed Registry JSON Format

When registry.remoteUrl points at a Git repository, ReqPack can sync registry JSON files from the configured registry.remotePluginsPath.

Current default main registry URL in app startup:

• https://github.com/Coditary/rqp-registry.git

Each plugin entry is stored in a JSON file whose filename must match the plugin name.

Example: registry/d/dnf.json

{
  "schemaVersion": 1,
  "name": "dnf",
  "source": "git+https://github.com/your-org/reqpack-dnf-plugin.git@v2.0.0",
  "description": "Fedora DNF wrapper",
  "role": "package-manager",
  "capabilities": ["exec", "network"],
  "ecosystemScopes": ["rpm", "fedora"],
  "writeScopes": [
    { "kind": "temp" },
    { "kind": "user-home-subpath", "value": ".cache/dnf" }
  ],
  "networkScopes": [
    { "host": "api.osv.dev", "scheme": "https", "pathPrefix": "/v1" }
  ],
  "privilegeLevel": "sudo",
  "scriptSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "bootstrapSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "aliases": [
    { "name": "yum", "description": "Alias for dnf" },
    "fedora-dnf"
  ]
}

Rules enforced by parser and runtime:

• schemaVersion must be 1
• name must match the JSON filename stem
• source is required for main records
• hashes are strongly recommended and validated when present
• alias records point to the canonical plugin name

How Refresh Works

rqp update <system> and rqp update --all can refresh plugin wrappers.

Flow:

1. registry DB resolves the record,
2. if alias, it resolves the target record,
3. refreshed payload is fetched from source,
4. hashes are validated,
5. script or bundle is materialized under registry.pluginDirectory/<plugin>/,
6. plugin is reloaded.

For Git-backed registries, ReqPack also tracks the last synced commit and can update incrementally by diffing changed JSON files.

Bundled Sources vs Thin Wrappers

Registry records can reference:

• a plain script source,
• a bundle source that materializes a directory,
• an alias to another plugin.

Bundle source means ReqPack copies whole plugin directory, not only single .lua file. This is how metadata.json, reqpack.lua, run.lua, helper files, and scripts/ travel with plugin.

Thin wrapper trust matters when security.requireThinLayer = true. In that mode, ReqPack compares runtime plugin metadata against the registry trust record.

Best Practices for Registry Authors

• Always ship scriptSha256 and bootstrapSha256 when possible.
• Keep names lowercase and stable.
• Use aliases only for naming compatibility, not as a substitute for proxy logic.
• Fill role, capabilities, scopes, and privilege metadata honestly.
• Prefer Git tags for versioned plugin refresh behavior.
• Keep description human-readable because it can surface in list/info outputs.

Related Pages

• Writing Lua Plugins
• Data, State, and Trust

Prev: Testing Lua Plugins | Up: Extending ReqPack | Next: Building rqp Packages and Repositories