User Guide Remote Protocol Reference

Remote Protocol Reference

Prev: Remote Mode | Up: User Guide | Next: Using Native rqp Packages

This page is wire-level and schema reference for ReqPack remote mode. Use Remote Mode for operational workflow.

File Location

Remote profiles and remote users live in:

• $XDG_CONFIG_HOME/reqpack/remote.lua
• fallback: ~/.config/reqpack/remote.lua

Accepted Root Shapes

remote.lua may be written in multiple equivalent ways.

Accepted patterns:

1. file returns table containing profiles and/or users
2. file sets global profiles = { ... }
3. file sets global users = { ... }
4. file returns plain profiles table when no users table exists
5. file returns plain users table when no profiles table exists

If file does not exist, ReqPack behaves as if no profiles/users are defined.

profiles Schema

Minimal example:

profiles = {
  dev = {
    host = "127.0.0.1",
    port = 4545,
    protocol = "auto",
    token = "secret",
  },
}

Supported profile fields:

• host
• url
• port
• protocol
• token
• username
• password

Validation rules:

• profile must resolve non-empty host
• port must be 1..65535
• invalid profiles are skipped

Endpoint parsing

host or url can include:

• raw host
• host plus port
• scheme plus host plus port
• IPv6 bracket form such as [::1]:4545

Parsing rules:

• if endpoint contains scheme, scheme may set protocol
• if endpoint contains path, path is ignored after host/port extraction
• explicit port field overrides port parsed from host or url

Scheme-to-protocol mapping:

• tcp:// -> text
• text:// -> text
• json:// -> json
• http:// -> http
• https:// -> https

Explicit protocol strings:

• auto
• text
• json
• http
• https

Important current limitation:

• http and https are parsed but both client and server reject them as not implemented

users Schema

Example:

users = {
  admin = {
    token = "secret",
    isAdmin = true,
  },
  operator = {
    username = "operator",
    password = "hunter2",
  },
}

Supported user fields:

• token
• username
• password
• isAdmin

Validation rules:

• user must have token or password
• if password exists and username is omitted, username defaults to user id
• invalid user entries are skipped

Server Auth Resolution

Auth is required when any of these exist:

• at least one valid users entry
• server fallback --token
• server fallback --username plus --password

Resolution order:

1. if valid users registry exists, server authenticates against users
2. otherwise server falls back to CLI --token or --username/--password

This means valid users table overrides fallback CLI credentials.

Session identity tracks:

• authenticated state
• user id
• admin flag
• auth type string such as token, basic, fallback-token, fallback-basic, none

Text Protocol

Text mode is default server behavior unless --json forces JSON-only mode.

Authentication frames

Token auth:

auth token secret

Basic auth:

auth basic admin hunter2

If auth succeeds, server returns empty successful frame. If auth fails, server returns text error frame.

Command frames

Request is one line of plain text command.

Response header is:

OK <length>

or:

ERR <length>

Then server sends exactly <length> bytes of plain-text response body.

Client must read exact byte count, not wait for prompt.

Close commands

These close connection cleanly:

• quit
• exit

JSON Lines Protocol

JSON mode is line-oriented and one-shot friendly.

Request shape:

{"command":"list apt","token":"secret"}

Supported request fields:

• command
• token
• username
• password

Success response:

{"ok":true,"output":"...plain text command output..."}

Failure response:

{"ok":false,"error":"...plain text error output..."}

Notes:

• JSON mode does not support interactive shell
• JSON mode does not support local file upload
• built-in client rejects JSON profile with no forwarded command

Protocol Selection

Server side

• rqp serve --remote --json forces JSON protocol for every connection
• normal text-mode server can still auto-detect raw JSON request line when first line looks like JSON object

Client side

• protocol = json uses JSON client mode
• protocol = text uses text client mode
• protocol = auto currently behaves like text client mode

Upload Install Wire Behavior

Text protocol supports special upload command for remote install of one local file.

Client detects upload only for:

• install ... <local regular file>
• exactly one local file target

Client sends header line shaped like:

__reqpack_upload_install__ <size> <filename> <commandTemplate>

Then streams exactly <size> raw bytes.

Server-side envelope fields are:

• payload size
• uploaded filename
• command template containing placeholder __REQPACK_REMOTE_UPLOAD_PATH__

Server behavior:

• writes upload to temp file under system temp reqpack/remote-upload/
• sanitizes filename to safe basename chars
• substitutes temp path into command template
• executes resulting ReqPack command
• removes temp file after command finishes

Restrictions:

• only regular files
• one local file per install command
• text protocol only
• readonly server rejects upload after draining payload bytes

Readonly Rules

Readonly-safe actions are:

• list
• search
• info
• outdated
• sbom
• audit

Readonly still rejects requests if any request writes output file.

So these are blocked in readonly mode:

• install
• remove
• update
• ensure
• sbom --output ...
• audit --output ...

Admin Commands

Admin-only commands handled directly by remote runtime are:

• shutdown
• connections count
• connections list
• reload-config

Admin privilege comes from remote user entry isAdmin = true.

serve Parser Rules That Matter Remotely

rqp serve parsing rules:

• exactly one of --stdin or --remote is required
• --token cannot be combined with --username/--password
• --username and --password must appear together
• protocol flags require --remote
• remote-only flags are rejected in stdin mode
• --port must be 1..65535
• --max-connections must be > 0

Client-side Upload and Interactive Rules

Built-in rqp remote client behavior:

• forwarded command runs once and exits
• no forwarded command starts interactive text session
• interactive client tokenizes shell-like quoting; malformed quotes make command invalid locally
• upload helper rewrites local path to remote placeholder before sending upload frame

Unimplemented Areas

These names exist in config and parser surface, but are not implemented:

• serve --remote --http
• serve --remote --https
• remote profiles with protocol = "http"
• remote profiles with protocol = "https"

Document them only as placeholders, not supported features.

Related Pages

• Remote Mode
• Command Reference
• Configuration
• Configuration Reference

Prev: Remote Mode | Up: User Guide | Next: Using Native rqp Packages