0x65-e/mattcraig.tech

Source Code for mattcraig.tech, a static webserver written in Rust and hosted on Cloudflare Workers

mattcraig.tech: Serverless Website in Rust!

About

This website is written for Cloudflare Workers using Rust and the workers-rs crate. Cloudflare workers is a serverless, "function as a service" (FaaS) platform that runs across distributed data centers.

It serves static files stored in Workers KV, a serverless key-value store on the edge.

links.mattcraig.tech

The subdomain links.mattcraig.tech hosts another Worker that serves as a link shortener.

Usage

With wrangler CLI, you can build, test, and deploy to Workers with the following commands:

# compiles project to WebAssembly and will warn of any issues
wrangler build 

# runs Worker in an ideal development workflow (with a local server, file watcher & more)
wrangler dev

# deploys Worker globally to Cloudflare
wrangler publish

You will need to generate your own KV namespace and replace the values in wrangler.toml.

# creates a preview namespace
wrangler kv:namespace create "STATIC" --preview

# creates a production namespace
wrangler kv:namespace create "STATIC"

If you choose a name other than STATIC for your namespace, be sure to update the KV access in libs.rs and the namespace binding in wrangler.toml.

You may also want to change the name of your worker in wrangler.toml.

Static Files

Static files are stored in the static/ directory. To serve static assets, they must first be uploaded to Workers KV. This is possible to do in bulk using the included Powershell script kv-bulk-upload.ps1. This keys each file with its relative path from the static directory (or whichever base directory you specify), which makes it easy to see your website layout on the filesystem. For example, the file static/index.html is mapped to the key index.html in the KV, while static/assets/css/resume.css becomes assets/css/resume.css.

You will need to enable Powershell scripts in the Windows security settings to run the upload script. This script requires Powershell 6.0 or later, which is not installed by default in Windows 10 and Windows 11.

# uploads all contents of ./static/ directory to preview namespace
./kv-bulk-upload.ps1 -preview

# uploads all contents of ./static/ directory to production namespace
./kv-bulk-upload.ps1

By default, the script uploads everything from ./static/. If you wish to change this behavior, you can use the -base flag. The default namespace is STATIC. You can change this by using the -binding flag.

Binary Files

For binary files, the script uses the wrangler kv:bulk utility to upload base64 encoded versions to Workers KV, which automatically decodes them before storing the raw bytes. This ensures that the Worker can serve binary file formats without any special accomodation. Currently, the upload script only supports the following binary file formats:

• Images: jpg, jpeg, png, gif, webp
• Web Fonts: ttf, woff, woff2, eot, otf
• Documents: pdf
• Audio: wav, mp3
• Video: mpeg, mp4
• Archives: zip, 7z

This is the same list of binary file encodings supported by the Worker. If you wish to add more binary content types, add them to the array $BinaryExtensions in kv-bulk-uplad.ps1. Make sure to associate the approriate Content-Type header in libs.rs so that the Worker can serve the new file type (and submit a pull request upstream to add them for everyone!).

The default filename for bulk uploads is the file kv-bulk.json, which is included in the .gitignore for that reason. If you wish to change the default, you can do so with the -outfile flag. Keep in mind that the result of base64 encoding many large binary files can be very large, so you may want to delete the outfile after uploading.

Skipping Binary Files

If you wish to skip uploading binary files (e.g. because they take too long), use the -skipbinary flag.

Large Files

By default, the script skips files with a size larger than 100MB (to speed up CI/CD pipeline runs using GitHub Actions) and outputs a warning about a large file size. You can set a custom limit using the -limitsize flag:

# uploads all files smaller than 1GB
./kv-bulk-upload.ps1 -LimitSize 1000

Setting a limit of 0 disables the limit.

mattcraig.tech's Issues

404 Page Doesn't Respect Theme

The "404 Not Found" page doesn't respect the dark/light theme preference set on the main page. Since darkmode requires assets/js/darkmode.js, the fix will likely involve copying that code into the static 404 response.

Multiple encoding of binary files

encode.sh doesn't discriminate between files that are already encoded in base64 format. Update kv backend to store e.g. .jpeg.b64 files, and dynamically add .b64 to requests from client when getting from kv, then serve the decoded file as .jpeg

Link containers on transcipt have large margins

#43 added margin-top: 1em to .link-container h3 to resolve spacing issues on the resume page. This introduced unintentional issues on the transcript page since course headers also use h3 elements inside link containers.

Possible solutions:

• Add CSS classes for h3 elements to indicate whether they should be spacing-adjusted or not
• Modify the macro for course listings to manually style the h3 elements

This same issue may crop up again for h4 elements in the future, since their spacing was also adjusted. To resolve these issues, the best approach is probably to create new CSS classes.