FREQ ? File Requests

FidoNet FREQ (File Request) is a protocol that lets one node request specific files from another node over a binkp session. BinktermPHP supports FREQ in both directions: serving files to remote nodes that request them, and requesting files from remote nodes.

Table of Contents

1. Serving FREQ (inbound requests) - Enabling FREQ on a file area - FREQ passwords - Shared file links - Magic names - How requests are resolved - Denial reasons
2. Requesting files (outbound) - Bark .req file mode - binkp M_GET mode - Picking up files asynchronously
3. FREQ response routing
4. Admin interface
5. Configuration reference

Serving FREQ (inbound requests)

Enabling FREQ on a file area

FREQ serving is controlled per-file-area. To allow remote nodes to request files from an area:

1. Go to Admin ? File Areas and edit the area.
2. Enable the FREQ Enabled toggle.
3. Optionally set a FREQ Password (see below).
4. Save.

Only files with status = 'approved' in active, public, FREQ-enabled areas are served. Private areas are never served regardless of settings.

FREQ is also settable when creating a new area via the file area API.

FREQ passwords

If a file area has a FREQ password set, the requesting node must supply it. For .req file mode the password appears on the first line of the .req file prefixed with ! (e.g. !mysecret). For binkp M_GET mode it is appended as the last field of the M_GET frame per FSP-1011.

Leave the password field blank for open access.

Shared file links

Individual files can also be made FREQ-accessible without enabling FREQ for the entire area. When creating a share link for a file (Files ? Share), check the FREQ Accessible box. The file will then be resolvable by exact filename match even if its parent area does not have FREQ enabled, subject to:

• The area being public (not private).
• The file being approved.
• The share link being active and not expired.

Shared-file FREQ does not support area passwords.

Magic names

The following magic names are supported and resolve dynamically:

| Magic name | Response | |---|---| | ALLFILES | A combined ALLFILES.TXT listing of every FREQ-enabled file area and their approved files | | FILES | Alias for ALLFILES | | <AREA TAG> | A per-area listing (e.g. requesting UTILS returns UTILS.TXT for the file area with that tag) |

Magic name resolution is case-insensitive. The generated listings use a FILES.BBS-compatible format with filename, size, upload date, and description.

Magic names do not require a password and cannot be subject to size or timestamp filters.

How requests are resolved

BinktermPHP accepts FREQ requests through three channels, all handled by src/Freq/FreqResolver.php:

1. binkp M_GET (live-session FREQ)

During a binkp session the remote node sends an M_GET frame. BinkpSession parses it and calls FreqResolver::resolve(). If the file is found and all checks pass, it is sent immediately in the same session via M_FILE.

2. Bark .req file

The remote node transfers a file with a .REQ extension (named after its own net/node numbers, e.g. 007B01C8.REQ). After the inbound files are received, BinkpSession detects the .req file and processes it through FreqResolver. Fulfilled files are queued in the freq_outbound table and sent during the same or a subsequent outbound session to that node.

3. Netmail FREQ

A remote node sends a netmail with is_freq = true. The subject line contains one or more space-separated filenames (or magic names). An optional password may appear on the first non-blank, non-kludge line of the message body. FreqResolver::processNetmailFreq() resolves each filename and delivers fulfilled files back to the requesting node as netmail FILE_ATTACH messages via MessageHandler::deliverFreqResponse().

Denial reasons

| Reason | Meaning | |---|---| | not_found | Filename did not match any FREQ-enabled area or shared file | | password | Area requires a password and none was supplied or it did not match | | size_limit | File exceeds the size limit specified in the M_GET frame | | timestamp | File is not newer than the timestamp requested in M_GET | | not_available | File record was found but the file is missing or unreadable on disk |

All attempts (served and denied) are logged to the freq_log database table and visible in the admin FREQ log (see Admin interface).

Requesting files (outbound)

Use scripts/freq_getfile.php to request files from a remote node.

php scripts/freq_getfile.php [options] <address> <filename> [filename2 ...]

Bark .req file mode

The default mode. A .req file is built in memory, written to a temp directory, and attached to the outbound binkp session. The remote processes the .req on receipt and queues the requested files for delivery. The remote may send them in the same session or in a subsequent session when it polls you.

Example:

php scripts/freq_getfile.php 1:123/456 ALLFILES MYFILE.ZIP

With a password:

php scripts/freq_getfile.php --password=SECRET 1:123/456 MYFILE.ZIP

The .req file format (FTS-0008) is plain text: an optional !password line followed by one filename per line, each terminated with \r\n.

The conventional filename is eight uppercase hex digits derived from the remote's net and node numbers (e.g. net=0x007B, node=0x01C8 ? 007B01C8.REQ).

binkp M_GET mode

Use -g for live-session FREQ (FSP-1011 M_GET). This sends the request during the binkp session itself and expects the remote to respond in the same session with M_FILE. Only use this when the remote node is known to support binkp M_GET FREQ natively (e.g. another BinktermPHP node).

php scripts/freq_getfile.php -g 1:123/456 ALLFILES

Options

| Option | Description | |---|---| | -g | Use binkp M_GET (live-session FREQ) instead of .req file | | --user=USERNAME | Store received files in this user's private area (default: first admin) | | --password=PASS | Area password required by the remote node | | --hostname=HOST | Override hostname; skip nodelist/DNS lookup | | --port=PORT | Override port (default 24554) | | --log-level=LVL | DEBUG, INFO, WARNING, or ERROR (default INFO) | | --log-file=FILE | Log file path (default: data/logs/freq_getfile.log) | | --no-console | Suppress console output |

Every request is recorded in the freq_requests_outbound table by FreqRequestTracker before the session opens. This allows asynchronous FREQ responses (files arriving in a later session) to be correctly routed to the requesting user.

Picking up files asynchronously

If the remote cannot reach you (no inbound binkp port), the remote will queue the files and wait for you to poll. Use scripts/freq_pickup.php to open an outbound session and collect them:

php scripts/freq_pickup.php 1:123/456
php scripts/freq_pickup.php 1:123/456 --hostname=bbs.example.com

This simply opens a binkp session; any files the remote has queued for your address are transferred normally and FreqResponseRouter routes them on receipt.

FREQ response routing

When files are received in a binkp session, FreqResponseRouter::routeReceivedFiles() is called with the remote node address and the list of received filenames. It looks up all pending entries in freq_requests_outbound for that node and matches received filenames case-insensitively against the requested filenames.

Matched files are moved into the requesting user's private incoming file area via FileAreaManager::storeFreqIncoming(). The corresponding freq_requests_outbound record is marked complete.

Files that do not match any pending request are left in data/inbound/ for process_packets to handle (FTN packets, TIC files, netmail FILE_ATTACH attachments, etc.).

Limitation: Magic names (e.g. ALLFILES) cannot be auto-routed because the remote chooses the actual filename at fulfillment time (e.g. ALLFILES.TXT). When requesting magic names, use a specific --user so that received files with unexpected names can be identified manually if they are not auto-routed.

Admin interface

FREQ Log ? /admin/freq-log

Displays all FREQ serving activity: requesting node address, filename requested, whether it was served or denied, denial reason, file size, source (binkp M_GET, .req, or netmail), and session ID. Useful for auditing what remote nodes are requesting and diagnosing why requests are being denied.

Nodelist node view ? /nodelist/view/<address>

When ENABLE_FREQ_EXPERIMENTAL=true is set in .env, a Request ALLFILES button appears on the node detail page for admin users. This sends an ALLFILES FREQ request as a netmail is_freq message to the selected node. It is a convenience shortcut for requesting file listings without using the CLI.

Configuration reference

| Setting | Default | Description | |---|---|---| | ENABLE_FREQ_EXPERIMENTAL | false | Set to true to show the FREQ request button on nodelist node pages (admin only) |

File area FREQ settings are configured per-area in Admin ? File Areas:

| Field | Description | |---|---| | freq_enabled | Whether remote nodes may FREQ files from this area | | freq_password | Optional password required for FREQ access to this area |

Key source files:

| File | Purpose | |---|---| | src/Freq/FreqResolver.php | Resolves inbound FREQ requests (M_GET, .req, netmail) | | src/Freq/FreqResult.php | Result value object returned by the resolver | | src/Freq/FreqRequestTracker.php | Tracks outbound FREQ requests for response routing | | src/Freq/FreqResponseRouter.php | Routes received files to requesting users | | src/Freq/MagicFileListGenerator.php | Generates ALLFILES.TXT and per-area listings | | scripts/freq_getfile.php | CLI tool for requesting files from a remote node | | scripts/freq_pickup.php | CLI tool for collecting asynchronously queued FREQ responses |