citizennet/purescript-httpure

A web framework written in PureScript.

purescript-httpure's Issues

Implement full routing

Currently, routing only matches exact strings. We should implement parameters, optional segments, etc.--we should support what express.js supports.

Add middleware example

Re-export Response in top-level HTTPure module

Currently only ResponseM is re-exported, but Response is not.

Add post example

Add a more ergonomic API around path segment matching

The Problem

The current API for matching path segments is entirely built around the Lookup typeclass. This works, but it can get clunky for some common things. For example, you can do this:

router :: HTTPure.Request -> HTTPure.ResponseM
router request@{ path }
  | path !@ 0 == "something" = somethingRoute request
  | otherwise                = HTTPure.notFound

But that will send any request whose first segment is "something" to somethingRoute. Likely the intent is to only send the request to somethingRoute if it has exactly one segment, which is "something", and you'd have to do something like this:

router :: HTTPure.Request -> HTTPure.ResponseM
router request@{ path }
  | path !@ 0 == "something" && length path == 1 = somethingRoute request
  | otherwise                                    = HTTPure.notFound

The API can become very painful as you have longer paths, e.g.:

path !@ 0 == "something" && path !@ 1 == "anotherThing" && path !@ 2 == "somethingElse" && length path == 3

And that doesn't even include doing things like enforcing specific requirements for certain pattern-based path segments, which requires significantly more complexity.

Proposed Solution

router :: HTTPure.Request -> HTTPure.ResponseM
router request@{ path }
  | path =~ "/something"                            = somethingRoute request
  | path =~ "/foo/\d+"                              = fooRoute request
  | path =~ "/something/anotherThing/somethingElse" = ...
  | otherwise                                       = HTTPure.notFound

Introduce two new binary operators, =~ and ==~. These operators take a Path on the left side, and a String on the right side. The Path will be matched against the String using some set of rules heavily inspired by Express's routing engine. =~ will be used for case-insensitive routing, where ==~ can be used for strict (case-sensitive) routing.

The only real change I'm aware of over what express does is that we'll have to come up with a different API around route parameters. Of course, that could be as simple as replacing :namedParameter: with \w+ and using Lookup to reference the parameters. If there were some way to even use the named parameters approach that Express uses, it would be awesome, but I don't see how that would be possible in a purely functional world (at least, without introducing a significantly more complex API, which isn't really worth it--it's a fairly small thing, and if it can't be done without an overly complex API, it's not worth changing to it).

Add support for reading headers

Write quick start guide / examples

Re-export Query and Status

Query and Status are missing in the top-level HTTPure module.

Add a better API for setting the content type

Add `sendFile` helper

Should take a path, automatically read and buffer the file, and automatically set the Content-Type response header.

Implement before/after middleware

We should have the ability to run middleware before or after the routes are executed.

Convert most usage of `Foreign.Object` to `Map`

Most usage of Foreign.Object should be using Map from https://github.com/purescript/purescript-ordered-collections instead of using Foreign.Object. Current usage is for query parameters and headers.

Ensure formatting follows purescript convention

Some places in the codebase don't follow purescript style convention. That should be cleaned up.

Determine if we want websockets support

This may or may not be something we want to do. Express supports websockets, but I'm not convinced that HTTPure should--WS is a very different protocol than HTTP or HTTP/2 and I'm not sure that HTTPure should cater to those differences.

Likely some other framework should be implemented outside HTTPure to support websockets in PureScript, but this ticket remains open as an investigation until we've decided for sure if we do or do not want to support WS.

Add guides

• Routing
• Writing middleware

Support PureSctript 0.12

Investigate `forkAff`

I believe that we should be using forkAff when running the router. We should investigate implications of doing that.

Add quick start in README.md

Test all the things!

Add first round of unit/integration tests.

Provide a way to stop serving

This will also significantly simplify the example code, as it will allow us to reuse the same port for all examples

Add support for writing headers and status

The fields are already expected of all routes but are not actually written out currently.

Support binary response body

Serving e.g. image data is not currently possible because response body is always a UTF-8 encoded string.

Use upstream `purescript-node-http`

Add tooling for working with query parameters and path segments

Handle exception thrown by `Stream.onDataString` and ST effect used by `Body.read`

Currently the execption propagates through the stack. HTTPure should be exception-free, so we should handle this.

Complete all response statuses

Make query parameters and headers use Maybe type instead of defaulting to "true" and using empty string for nonexistent parameters (and update guides)

Complete all request methods

ResponseM should be async

Native compile

https://github.com/andyarvanitis/purescript-native

Better error handling

We need better sad-path handling. Things like:

• Request closed by client while in flight
• Exception while running router
• Others?

Add more response status codes

Update guides

Go through guides and update based on changes since the last release, and double check that all examples are still accurate

• Add notes on Body typeclass, along with different instances (String, Buffer, Stream.Readable, etc)
• Add notes on default headers (Content-Length, etc) and mechanism for overriding
• Add some notes on common path matching techniques and tools (things like array pattern matching, dealing with case sensitivity, purescript-routing, etc)

Wrap all node-http methods

purescript-node-http has a large surface area, and much of the functionality is currently unavailable through purescript-httpure. We should ensure that all functionality available through purescript-node-http is exposed somewhere in purescript-httpure.

Implement chunked requests

Must support HTTP 1.1 chunking

Add support for reading body

Add performance tests / benchmarks

Create show instances for path and query (and maybe request?)

Implement HTTPS

Currently, we only have HTTP support. We should add HTTPS support.

Implement chunked callback API

See thread here

Make weird pattern around response and response' consistent with response helpers

Make route methods be separate data constructors.

Currently Route is a data constructor, and routes are created like:

routes = [
  { method: Get, route: "/hello",   handler: helloHandler },
  { method: Post, route: "/goodbye", handler: goodbyeHandler }
]

A better API would be to have Route have data constructors for each HTTP method, and construct routes something like:

routes = [
  (Get "/hello" helloHandler),
  (Post "/goobye" goodbyehandler)
]

Add HTTP/2 Support

Add travis configuration

Content-Length header is wrong for non-ASCII bodies

When computing the value for the Content-Length header, String.length is used. This is not correct for non-ASCII strings, as each character gets encoded to two or more bytes in UTF-8. For example, when using the string "äö" as the response body, there's Content-Length: 2 but the content is actually 4 bytes long.

Abstract node-http so it can be swapped

In the interest of centralizing dependencies and preparing to be able to be native-compiled, we should centralize and abstract purescript-node-http uses so that it can be easy to swap out http backends when necessary.

Add Content-Length header

We should be calculating the Content-Length header based on the size of the response.

Add release guide/process

Create Headers.header function to create a singleton Headers

Separate SecureServerM from ServerM

ServerM (and HTTPureM) has no need for the FS effect. It's only there for reading the key and cert files for secure servers. It would be better to have a SecureServerM type separated from the ServerM type, which pulls in the FS effect.