RFC: Improvements to webserver

[vlidholt]

Serverpod comes with a built-in web server called Relic. It's still experimental, and it would be nice to clean it up and make it top-notch, like the rest of Serverpod. 🚀

There are many use cases for the web server:

• Serve a Flutter web app.
• Build websites that use the same database as the API server.
• Create webhooks.
• Create REST APIs that look a specific way. I.e., complete control over status code, request types, headers, etc.

The main benefit of having a good web server bundled with Serverpod is that developers can use the Serverpod sessions and ORM. This means that a lot of code can be shared between the generated API and a website or custom API.

Improvements

The overall architecture for Relic looks sound, but it would be nice to improve in certain areas.

• [ ] Routing. Providing an easier way to pattern-match paths and automatically extract components from them would be nice. We can take inspiration from packages like Shelf, Dart Frog, and Pharaoh here. Looking at packages from other languages would also be smart. Let's be best in class here!

  2489

• [ ] Abstraction of requests and responses. Add a layer of abstraction for requests and responses. This would pave the way to better support middleware, and making the interface cleaner. It would also make the interface future proof, in case we want to move away from dart:io.

  2495

• [ ] Web sockets. Relic currently doesn't support web sockets. We should make that possible.

  2497

• [ ] Middleware. Add support for middleware, as it can be used for things like custom logging, authentication, data validation, error handling, or other logic. Again, we should look at other frameworks to do something really good here.

  2499

• [ ] Sharing static files. There is a route made for sharing a directory of static files. It works, but the API could be clearer and easier to understand. We should also support more MIME types. It should also be possible to add additional types.

  2498

• [ ] Make Flutter web easy. Serving a Flutter app may be the most common reason to use Relic. We should make it very simple to set up, compile, and host a Flutter web app. This may be best in the form of a tutorial.
• [ ] Support modules. Make it possible to place web routes in Serverpod modules. This would make building modules for integrations like payments requiring custom webhooks easier.

  2500

• [ ] Testing framework. We should integrate Relic with the new testing framework.

  2494.

• [ ] Authentication. It should be possible (through pre-built middleware?) to access the same authentication system as for Serverpod's generated endpoints.
• [ ] Tests. Improve the test suite for Relic. There are a couple of tests, but it would be nice to cover a larger surface. Documentation. Add examples and proper documentation for the webserver.

Ideas for the future

These are ideas that we can add in the future without breaking any of the new core features.

• Improved templates. Relic has a template engine that uses the Mustache library. A template combined with a Dart class forms a Widget, which is analogous to a Flutter widget. It would be cool to support Relic widgets that resemble some of the static Flutter widgets (Container, Row, Padding, Text, etc). We could also generate widgets (possibly without a template file) that correspond to all the default tags in HTML.

[codekeyz]

Awesome stuff @vlidholt. Is Relic added in the alpha version currently on pub.dev? I'd love to see how this turns out.

[vlidholt]

@codekeyz, Relic is already part of Serverpod 1.0 and later.

[dkbast]

Supporting modules is probably one of the most important features if the goals is to have a "module economy" where there are modules for most common use cases (and not just libraries which you then still need to plugin yourself). Especially receiving and sending to webhooks is something that will probably be very valuable (e.g. make, zapier and all the payment providers as well as newsletter, marketing & crm tools or when working with any third party ecommerce framework).

[Maksimka101]

From my point of view most people will use the webserver for webhooks and static files serving. So I'd like to see the high level routes api as well as a convenient file serving functionality. Hope this issue is the right place to share my expectations :)

[ali-esmailie-dev]

I can't find any documentation for the relic. Please help me to implement Rest API with relic. @vlidholt

[dinko7]

Here are some things I'd like to see in Relic:

• Shelf middleware adapter: I've tried (almost) every Dart backend framework and while some of them offer improved speed or developer experience, generally losing the power of Shelf's ecosystem is just not worth it. Pharaoh (and now Serinus) are the exceptions to the rule because I can leverage some middleware.
• OpenAPI spec generation for Relic: I can't stress this enough. Having ability to at least generate the first draft of the OpenAPI spec is mandatory. Documentation can then be used for internal purposes, for external documentation (eg. webhooks for other people) and generation of client libraries. In addition to this, a prebuilt Swagger page would be the cherry on top.
• Reuse: an easy way to expose already defined Serverpod Endpoints as a REST compliant ones. Maybe codegen/macros can be used here as well?

Some other notes:

• Routing: I really like the work @codekeyz did with Spanner and using a Radix tree for HTTP routing. Most of the modern web frameworks nowadays use the same approach (Shelf uses a list 😅).
• Make Flutter web easy: I'd say that the biggest use case is the exact opposite: JS/TS-based framework used for web interface instead of Flutter. This ties into the OpenAPI spec generation because it would be easy to generate JS client for the specified endpoints.

[codekeyz]

Thanks for the mention @dinko7