FEP 001

FujiNet Enhancement Proposal (FEP) 1

Using URLs in Client Applications

Abstract

This document defines a standard approach for using URLs in client applications on the Atari 8-bit platform (using SIO), Apple2 (SmartPort), ADAM (ADAMnet), and others, leveraging the FujiNet device for protocol adaptation and all network communication. It describes the structure of a URL, encoding and decoding mechanisms, and how a client application can interact with FujiNet to retrieve data from RESTful APIs.

Motivation

With FujiNet providing a powerful network interface for retro computing platforms, client applications must efficiently interact with remote resources. The goal of this FEP is to establish a structured methodology for constructing, parsing, encoding, and decoding URLs, ensuring seamless communication between client applications and FujiNet's ESP32-based protocol adapter.

URL Structure

A URL (Uniform Resource Locator) consists of multiple components as defined by RFC 3986:

scheme://[user:password@]host[:port]/path[?query][#fragment]

Components:

• Scheme: Specifies the protocol (e.g., http, https, ftp).
• Userinfo (Optional): Credentials for authentication (user:password).
• Host: Domain name or IP address of the resource.
• Port (Optional): TCP port number (default: 80 for HTTP, 443 for HTTPS).
• Path: The specific resource location on the host.
• Query (Optional): Key-value parameters (?key=value&key2=value2).
• Fragment (Optional): Internal resource reference (#section).

Example URLs:

• http://example.com/resource
• https://user:[email protected]:443/data?format=json#section

URL Parsing on FujiNet

The FujiNet firmware running on the ESP32 will handle URL parsing and translation. The Atari 8-bit client application will:

1. Define a URL string in ATASCII format.
2. Send the URL to FujiNet over SIO.
3. FujiNet will:
   • Convert ATASCII to ASCII.
   • Parse the URL and extract components.
   • Encode an HTTP request.
   • Send the request over TCP/IP.
   • Receive and decode the HTTP response.
4. The parsed response is returned as key-value pairs to the client.

Sample URL Breakdown and Parsing

To illustrate URL parsing, consider the following example URL:

https://user:[email protected]:8080/data/info?query=test#section1

Breaking it down into components:

Component	Value
Scheme	https
Userinfo	user:pass
Host	api.example.com
Port	8080
Path	/data/info
Query	query=test
Fragment	section1

After parsing, FujiNet prepares the URL for encoding by replacing special characters with their respective percent-encoded values.

Encoded URL

https%3A%2F%2Fuser%3Apass%40api.example.com%3A8080%2Fdata%2Finfo%3Fquery%3Dtest%23section1

This encoded URL can then be used in network requests, ensuring proper handling of special characters.

Encoding and Decoding URLs

URL Encoding (Percent-Encoding)

Certain characters must be encoded for proper transmission. FujiNet’s URL encoder will replace special characters with % followed by the hexadecimal ASCII code.

Character	Encoded Form
Space	%20
#	%23
?	%3F
&	%26
/	%2F

URL Decoding

FujiNet will decode incoming URLs by replacing percent-encoded characters with their original representations before processing the request.

Client Application Implementation (C / cc65)

A simple FujiNet-aware client program for the Atari 8-bit computer:

#include <stdio.h>
#include <string.h>

define URL "http://api.example.com/data?item=42"

typedef struct {
    char key[32];
    char value[128];
} KeyValue;

int main() {
    printf("Sending request to FujiNet...\n");
    // Send URL over SIO
    send_url_to_fujinet(URL);
    
    // Receive response
    KeyValue response[10];
    int count = receive_response_from_fujinet(response);
    
    // Display key-value pairs
    for (int i = 0; i < count; i++) {
        printf("%s: %s\n", response[i].key, response[i].value);
    }
    
    return 0;
}

Conclusion

By offloading URL handling and network requests to FujiNet, we enable efficient client applications with minimal overhead on Atari 8-bit systems. This FEP establishes a structured methodology for URL usage, ensuring compatibility and ease of development for FujiNet-enabled applications.