Skip to content

Home

Jump to bottom
Alistair Turnbull edited this page Sep 24, 2025 · 15 revisions

This page can be used for hacking the design/spec together until it can be moved to a .md file in the repo

petite_http desiderata/spec

Missing features:

  • A templating system that prevents escaping errors in the response.
  • HTTP redirects.
  • Serving pages with radically different request parameters, deserving of different Params types.
  • handle_post().

Present features:

  • A system that prevents escaping errors in the request.
  • Rust's ? operator generates HTTP error responses.
  • You never see a Url.
  • Useful utilities for manipulating and testing parts of URL paths.

Informal criterion is "anything needed by Ocularity, photo server, Nifki, questionnaire, congenialwiki". It's far from a feature-complete web app framework, as it should be. Just the 80% functionality.

Handle/dispatch

Serving pages with radically different request parameters, deserving of different Params types. For this, I think a possible design is a dispatch() function that picks a Handle implementation and passes it to a callback. Then different URL paths can have different Params types, and each be statically type checked.

Templating

We should provide a templating system sufficient to prevent escaping errors in the response. < must be &lt;; & must be &amp;, and so on. Additionally, any URLs included HTML attributes must be %-encoded and then HTML-encoded.

Escaping bugs are the most common bugs after memory allocation. At least, that was true a few years ago; memory allocation has got a lot better since.

Libraries exist for all the encoding steps. Our job is to make correct usage obvious and convenient.

For this the minimum viable product is a trait ToHtml with these implementations:

  • &'static str (no escaping; static strings should be statically escaped)
  • String (HTML escaping; dynamic strings are typically unescaped)
  • Url (HTML escaping; already %-escaped)
  • struct Filename(String) (%-encoding then HTML escaping; use when constructing URLs from fragments)

Nice To Haves:

  • Numbers, char, bool (HTML escaping)
  • Concatenation of [dyn ToHtml]
  • Interpolation of HashMap<&str, dyn ToHtml> or similar into a static template
  • Query strings represented as HashMap<&str, dyn Display> or similar (%-encoding, then add ? and &s, then HTML-encode)

I'm thinking that HttpOkay::Html payload should be a Box, i.e. the handler can return a ToHtml, and petite_http will escape it correctly.

Third-party templating

If use a templating engine such as ramhorns, it will generate correctly escaped HTML. To avoid escaping it a second time, return it as Http::Text(..., content_types::HTML) just like any other text-based file type. HttpOkay::Html(...) is only intended for apps that want to generate their own HTML correctly.

Dependencies policy

let's not go down the npm route of oneliner dependencies; but equally, let's continue to use url::Url which appears to have already gone down that route... (I looked for viable alternatives and there aren't any.)

Development

  • Have a think about how you want to do testing and publishing to crates.io.
  • We should probably have an example web app that you can cargo run in the petite_http crate.
  • yeah it should be done properly; i mean we can get it working for our use cases, but committing to a good v1.0 down the line

Clone this wiki locally