Add form parsing docs

[nguiard]

Hi, thanks for this library, it's very nice to have!

Say you want to make the most basic of web apps. Say you're coming to Julia from a non-data science background, but you're quite experienced making web apps in other languages, and you're just fiddling around to see how it feels in Julia. You have a user, a page, and a form on that page that the user can fill and submit. The default encoding for forms sent with POST is application/x-www-form-urlencoded, and the HTTP standard encourages you to use POST for anything that may modify data server-side, for good reason.

Seeing how HTTP.jl and Oxygen.jl seem to support some advanced features like plots, WebSockets, protobuf etc, you'd be surprised, then, to find out that currently:

• neither HTTP.jl nor Oxygen.jl mention this most basic use case (handling forms received with application/x-www-form-urlencoded) anywhere in their docs
• the code in HTTP.jl for sending data with application/x-www-form-urlencoded just uses return write(stream, URIs.escapeuri(body)) and thus is incorrect, because URIs.escapeuri encodes for URLs, and URLs and application/x-www-form-urlencoded encodings are actually different (see Add function for encoding with application/x-www-form-urlencoded and use it internally JuliaWeb/HTTP.jl#1138)
• if you scour the docs on how to handle a form sent to your server, thinking "it's impossible they don't mention this case, right?", and you're not on top of your web encodings knowledge, you may find the example for handling query parameters (https://github.com/OxygenFramework/Oxygen.jl?tab=readme-ov-file#query-parameters) and think you might just be able to use this queryparams function on the body of the incoming request. Seems to work, but then you silently end up with My+Blog+Post+Name instead of My Blog Post Name in your database. Why? Because the browser of course correctly used the application/x-www-form-urlencoded encoding to send the form, and the + are not decoded as by queryparams (which is correct for URL encoding, but incorrect for forms).

While it is quite easy to work around these problems in your own app if you know what you're doing, I guess it would be extremely confusing to a newcomer, and quite frustrating to experienced web devs to have to do that themselves, who then might just flee from the language for any serious web-related stuff. Which is sad because having a strong web ecosystem would make Julia much more credible as a general-purpose programming language. For me, coming from Rust (where admittedly, the web ecosystem is incredibly rock-solid), the Julia web ecosystem currently feels very flimsy (not really because of the lack of libraries, but more because of these kinds of basic use cases not accounted for, popping up here and there).

Generally, I suggest there should be an effort to make the Julia web basics solid, correct, unsurprising. I think the above story should not happen for people trying Julia for the web. Maybe I can help, although I'm quite new to Julia.

More specifically, for Oxygen.jl, I suggest the case of application/x-www-form-urlencoded should be explicitly documented, even if to say that it doesn't support it because HTTP.jl doesn't currently support it. If I get some time, I'll work on a PR for HTTP.jl to support the case, and I can do a PR for Oxygen too if you're ok with that.

[ndortega]

Hi @nguiard,

This case should already be covered, below is a short example of how to parse out the form data from a request. In this scenario, you don't have to worry about the weird URL encodings as they are handled by the formdata() function.

Assuming this covers this case, I think we could rename this issue to something like "add form parsing docs"

using Oxygen

@get "/" function()
    html("""
    <form action="/form" method="post">
        <label for="firstname">First name:</label><br>
        <input type="text" id="firstname" name="firstname"><br>
        <label for="lastname">Last name:</label><br>
        <input type="text" id="lastname" name="lastname"><br><br>
        <input type="submit" value="Submit">
    </form>
    """)
end

@post "/form" function(req)
    data = formdata(req)
    println(data)
    return data
end

serve()

[nguiard]

Hi, oh that's perfect! Thanks and sorry for the long rant then haha. I'll change the issue name. Would you like me to try my hand at a PR for documenting the case?

[ndortega]

No worries, this feature was completely undocumented.

And you don't have to do that, I can add this later tonight. But I definitely won't stop someone else from writing docs. If you want to give it a shot, I only ask that you keep it concise and place it after the query parameters section in the readme.

Also, don't forget to cd into the docs directory and run the docgen.jl after making your changes. This copies the changes over to another readme file that is used by documenter.jl to build the docs site.

[nguiard]

Ok thanks. I'll let you handle this then, but maybe I'll come back with a few more docs at some point. Thanks again.