roc-lang / roc-lang/basic-webserver

Expose standard Base64 encoding as a platform module

Open
#197 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement good first issue
Dominant language
HTML
Stars
107
Forks
20
Avg merge
1d 17h
Merged PRs (30d)
11

Description

Summary

Expose standard padded Base64 encoding as a small pure pf.Base64 module:

import pf.Base64

encoded = Base64.encode(bytes)

with an initial API of:

encode : List(U8) -> Str

Motivation

While adding a multimodal outbound HTTP request to a basic-webserver
application, I needed to embed JPEG bytes in a JSON data URL:

image_url = "data:image/jpeg;base64,${Base64.encode(image)}"

The application currently has to carry its own Base64 implementation.

This need already exists inside basic-webserver itself. The
form-file-upload.roc example
contains a private encoder so it can render an uploaded PNG as a data URL.
Extracting that implementation into the platform would remove the duplication
and make a common web protocol primitive available to applications.

Other common uses include Basic authentication, MIME/content-transfer
encoding, webhooks, and binary values in JSON APIs.

Proposed scope

  • Add a pure platform/Base64.roc module.
  • Expose it from platform/main.roc.
  • Implement the RFC 4648 standard alphabet with = padding.
  • Document that the output is ASCII and accepts arbitrary bytes, not only
    UTF-8 input.
  • Replace the private implementation in examples/form-file-upload.roc with
    the exposed module.
  • Test the RFC 4648 vectors, empty input, one- and two-byte tails, and
    non-UTF-8 binary input.

This should require no hosted operation or ABI change.

Decoding, unpadded output, and the URL-safe alphabet can be separate follow-up
features when there is a concrete use case for their API and error contract.

Acceptance criteria

  • Applications can import pf.Base64 and encode List(U8) as standard
    padded Base64.
  • The implementation matches RFC 4648 test vectors and handles arbitrary
    binary input.
  • The file-upload example uses the shared module instead of maintaining a
    private encoder.
  • The generated platform API documentation includes the module and its
    encoding contract.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the private encoder in examples/form-file-upload.roc and the module exports in platform/main.roc. Trace how platform modules are tested and documented, then use those entry points to define platform/Base64.roc and its RFC 4648 test coverage. Done means the example imports pf.Base64, binary and edge-case tests pass, and the generated API documentation describes the encoding contract.

Written by the indexing model from the issue text.

Assessment

Domain
api, backend, documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.