Skip to main content

Mounting into HTTPS filesystem

Spectranext allows you to mount HTTPS URLs as read-only filesystems directly from Spectrum programs. This allows accessing files hosted on web servers as if they were local files.

This means that files/tapes can be hosted anywhere and not just TNFS. However, it is important to note that such an endpoint would not work on the original Spectranet, but it is very convenient.

Overview​

HTTPS Filesystem provides:

  • Web-Based File Access: Mount HTTPS URLs as filesystems
  • Standard VFS Interface: Uses Spectranet's standard VFS (Virtual File System) API with https:// prefix
  • Read-Only Access: Files can be read directly from web servers
  • Directory Listing: Browse directory contents using index.txt files
  • Transparent HTTPS/TLS: All communication is encrypted using TLS

Mounting HTTPS Filesystems​

To use HTTPS filesystem, you must first mount it using an HTTPS URL.

Mounting an HTTPS URL​

#include <spdos.h>

mount(0, NULL, NULL, "/path", "example.com", "https");

The URL should point to a directory on the web server. The path can include subdirectories:

mount(0, NULL, NULL, "/test/https", "spectranext.net", "https");

Unmounting​

umount(0);

Accessing Files​

Once an HTTPS filesystem is mounted, you can access files directly by their path. Files are fetched transparently over HTTPS when opened.

Opening Files​

#include <spdos.h>
#include <fcntl.h>

int fd = open("file.txt", O_RDONLY, 0);
if (fd >= 0) {
    // File opened successfully
    // ... read from file ...
    close(fd);
}

Reading Files​

Files are downloaded automatically when opened.

#include <spdos.h>
#include <unistd.h>

int fd = open("data.bin", O_RDONLY, 0);
if (fd >= 0) {
    unsigned char buffer[1024];
    ssize_t bytes_read = read(fd, buffer, sizeof(buffer));
    close(fd);
}

Directory Listing​

To enable directory listing (%cat, opendir, etc.), you must create an index.txt file in each directory you want to browse. The HTTPS filesystem will fetch this file to determine the directory contents.

See index.txt file example.

index.txt Format​

The index.txt file uses a simple key=value format, with one entry per line. Each line contains space-separated key=value pairs:

For files:

type=file name=filename.txt size=1024

For directories:

type=dir name=subdirectory

Example index.txt​

Here's an example index.txt file:

type=file name=readme.txt size=1234
type=file name=program.bin size=4096
type=dir name=docs
type=file name=data.dat size=8192

Required Fields​

  • type: Must be either file or dir
    • file: Regular file entry
    • dir: Directory entry
  • name: The filename or directory name
  • size: File size in bytes (required for files, ignored for directories)

Directory Listing Operations​

Once index.txt is present, you can use standard directory operations:

#include <spdos.h>
#include <dirent.h>

DIR* dir = opendir(".");
if (dir) {
    struct dirent* entry;
    while ((entry = readdir(dir)) != NULL) {
        printf("Entry: %s\n", entry->d_name);
    }
    closedir(dir);
}

Server Setup​

To make your files accessible via HTTPS filesystem:

  1. Host files on an HTTPS server: Ensure your web server supports HTTPS with valid TLS certificates.
  2. Create index.txt files: For each directory you want to browse, create an index.txt file listing its contents. This is optional, if you don't want directory listing, files would still fetch.

Example Server Structure​

https://example.com/files/
├── index.txt
├── boot.zx
├── program.tap
└── docs/
    ├── index.txt
    ├── manual.pdf
    └── guide.txt

The root index.txt would contain:

type=file name=boot.zx size=60
type=file name=program.tap size=4096
type=dir name=docs

And docs/index.txt would contain:

type=file name=manual.pdf size=56789
type=file name=guide.txt size=2345

Limitations​

  • Read-Only: HTTPS filesystem is read-only. Write operations are not supported
  • No Write Operations: write(), mkdir(), rmdir(), unlink(), and rename() operations are not supported
  • Maximum Entries: Directory listings are limited to 128 entries per directory