roc-lang / roc-lang/basic-webserver
Expose standard Base64 encoding as a platform module
Nobody has claimed this yet.
- 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.rocmodule. - 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.rocwith
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.Base64and encodeList(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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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