First time using Falco

[nojaf]

Hey there,

Just gave Falco a whirl for the first time. The docs looked neat, which piqued my interest.

Here are some random thoughts I had while exploring it. Feel free to ignore them; they might just be nitpicks.

To set the stage, I've dabbled with Giraffe before, but Suave is more my jam, mainly because it's straightforward and doesn't make me deal with ASP.NET Core's intricacies. My grasp on ASP.NET Core isn't the sharpest, and that's probably going to show in some of my comments. Also, I'm one of the folks behind fsharp.formatting, so my views might be a bit skewed because of that.

So, without any particular order:

• A search feature in the docs would've been awesome. Had a few moments where I was like, "How do I do X in Falco?" Being able to just look up 'X' would have been great.
• The docs are pretty thorough, which is great. But I was left wanting some more common use-case scenarios. For instance, changing the web server's port—no clue how that's done in ASP.NET Core, so a quick search feature would have been handy here too.
• Kept seeing webHost [||] { in examples but had no idea what the empty array was for. A bit of a head-scratcher.
• Missed seeing a barebones HttpHandler example. I love seeing how to handle raw request headers and bodies and set response headers and bodies directly.
• An API documentation section is notably absent. Might be something to think about.
• What I really missed in Falco was a solid scripting story. Suave nails this, but I get the challenge due to the ASP.NET Core dependency. Jimmy's comment offers a workaround. Maybe a dotnet tool to automate this could be cool? Seems like a common issue for many projects.
• Had to enable CORS in a "I don't really care" kind of scenario. Something like this would have been handy:

webHost [||] {
   use_cors_unsafe true
}

Didn't want to fuss over CorsPolicyBuilder and CorsOptions for some localhost experiments.

• Noticed some code snippets missing open statements. If you used scripts in fsdocs, that could link directly to the actual code, keeping your docs synchronized and avoiding CI misses.

Like I said, these are mostly minor points, and you've done a fantastic job with the project!
Keep it up!

[nojaf]

Oh and maybe one example of grabbing a logger inside an HttpHandler would also be interesting.

[pimbrouwers]

Hey Florian,

Nice to meet you officially.

I appreciate the time taken to provide all of this feedback. It's invaluable to the progress of the library.

Some of the things you bring up are things I've thought about as well for some time. But, as a dad of two young kids and a demanding job, things don't always get the attention they deserve. I like to think I do a solid job on the critical stuff, and hopefully can continue to improve on the remainder as my time continues to free up.

Now, on to your questions.

• Re: Search feature
  • This is a good idea. I'll look into incorporating a Google Search widget.
• Re: Server configuration
  • I recognize I'm taking for granted that the user has prior experience with ASP.NET Core. I came to F# after a decade using ASP.NET MVC with C#. Building this framework was my way of battling my "MVC fatigue". But my bias is evident, and I'll look to provide better documentation on that.
  • For most server configuration, including yours about the port number, I recommend using the appsettings.json file which gets incorporated automatically for you. Documentation for this specifically can be found here.
• Re: Webhost initialization
  • This would be more familiar if you had background in ASP.NET Core. Basically, when you stand up a web host (now web application), you can optionally pass in the command line arguments for runtime configruation.
  • I have never loved the builder, which is why I have removed it in v5, in favour of a fluent builder that trues to provide a more broad working API versus a poorly designed DSL.
• Re: Barebones HttpHandler
  • Checkout the second code block, on this page.
• Re: Scripting
  • I had never thought of this as a thing. What exactly is the use case?
  • I don't see why having two files (App.fs, App.fsproj) and invoking with dotnet run is limiting?
• Re: CORS
  • Adding middleware that isn't contained in the DSL is best done using the add_middleware function and the extension method(s) found in Microsoft.AspNetCore.Builder.
  • I don't plan to offer these shortcuts in the future, they are a maintenance nightmare.
• Re: FSDOC
  • It's on my radar, mostly a time thing.
• Re: Examples
  • Better examples (after 4 years you learn a few things haha!) are coming with v5.

Thanks again for your time and interest. Really appreciate it.

[nojaf]

Hi Pim,

Thanks for your response to this post! I was hesitant to post it due to its detailed criticisms.

I understand time constraints might be an issue for you with this project. Life happens, and I completely understand. I'm not expecting any immediate actions; I'm simply curious about a few things.

Have you considered building a community around Falco, such as finding co-maintainers to help the project grow beyond your efforts? More contributors can be beneficial in the long term.

Regarding my interest, I'm looking for an excellent framework to build web servers in F# and see potential in Falco. The documentation is impressive, and such developer-first experiences are what F# needs more of.

Re: Search feature

fsdocs includes this feature. I might put together a small PR to demonstrate some capabilities.

Re: Server configuration, appsettings.json file

It's disappointing that an additional file is needed just to change the port. I understand this is more related to ASP.NET Core, but in a simple Node.JS project, everything could fit in a single file. That's the appeal of the scripting approach when all requirements fit into one file.

Re: Scripting

Sometimes, I need a quick, temporary web server. I'm not aiming for production or longevity, which is why Suave is appealing—it fits into a script file for fast iteration. You might suggest dotnet watch, but scripting is still quicker.

Re: CORS

Understood. I appreciated finding the exact documentation snippet I needed.

Re: Examples

I always appreciate a "recipes" page for quick learning.

Lastly, why is there an empty array in webHost?

Keep up the great work, Pim!