Operatic 0.7

Operatic defines a minimal standard interface to encapsulate your Ruby operations. The job of Operatic is to receive input and make it available to the operation, and to gather output and return it via a result object. This leaves you a well-defined space to write the actual code by implementing the #call method – and with so much of the ceremony taken care of it feels like writing a function but in a Ruby wrapping.

Version 0.7.0 introduces concrete Success/Failure result classes which brings a slight change to the API and may therefore impose some tweaks to your code.

In earlier versions an operation gathered data on its result object and marked the result as a success or failure. Now the operation gathers data on a separate Operatic::Data object and it’s the operation that controls the success/failure status by choosing the appropriate Success/Failure result class and initialising it with its data.

Operatic::Data could have perhaps been a plain Hash but I wanted to retain the ability to define a per-operation subclass with custom accessors (which remain accessible via the result thanks to the magic of #method_missing). I couldn’t use the Data class introduced in Ruby 3.2 because it’s frozen at the point of creation whereas in an operation data is gathered throughout execution and frozen on completion.

Having a concrete success/failure result class also makes pattern matching clearer by replacing an anonymous boolean ([true, { message: }]) with the self-documenting result class itself:

case SayHello.call(name: 'Dave')
in [Operatic::Success, { message: }]
  # Result is a success, do something with the `message` variable.
in [Operatic::Failure, _]
  # Result is a failure, ignore any data and do something else.
end

Altogether I’m pleased with the overall refactor, I think it’s resulted in a better API by more clearly defining the roles and responsibilities of each of the component parts.

Streaming Phlex from Sinatra

Sinatra supports streaming, Phlex supports streaming, but until recently I hadn’t put the two together in phlex-sinatra. Well now I have and from version 0.3 you can pass stream: true like so:

get '/foo' do
  phlex MyView.new, stream: true
end

When streaming is enabled Phlex will automatically flush to the response after a closing </head> which means that the browser can start processing external resources as quickly as possible while the rest of the view is being generated. Even with no further intervention this small change should improve your Time to First Byte and could improve your First Contentful Paint.

It took very little code to integrate Phlex with Sinatra’s streaming but it did require a lot of learning and understanding, some of which will be useful to you dear reader. The first thing to note is that streaming with Sinatra requires a compatible server like Puma (it appears that WEBrick isn’t compatible) but the main thing to be aware of is the assortment of buffers between your code and the receiving client.

Buffers buffers buffers

It’s normal for a web framework to wait until a page has been fully generated (to buffer) before sending the response – so that the Content-Length can be determined, among other things. Sinatra (et al) provides a way to bypass its buffer and write directly to the response, and it’s this object that’s passed to Phlex.

I was using curl to inspect the response and although I could now see the immediately-streamed HTTP headers (pass -i/--include to curl to include the headers in its output) the rest of the response was only shown once complete. I spent an age investigating both Sinatra and Phlex’s internals only to realise that everything was working correctly and the culprit was curl itself which has its own buffer. Curl behaves like other command-line tools and outputs lines but Phlex “uglifies by default” (it doesn’t add extra whitespace to generate pretty HTML) and this lack of newlines exacerbated the apparent problem – the trick is to pass -N/--no-buffer.

But streaming still wasn’t working as expected. It was then I discovered that Phlex has a buffer that’s automatically flushed after a closing </head> tag, but it’s otherwise left to the developer to choose if and when to call the provided #flush method (I’m guessing Phlex doesn’t write directly to the buffer due to some sort of performance penalty).

One more thing that I didn’t encounter while testing but that it’s worth being aware of is that other intermediaries can buffer the response without your knowledge, for example the reason for adding a X-Accel-Buffering=no header is explained here (the whole article is well worth a read).

When to use streaming

So… I think ideally you shouldn’t need to use streaming at all but it’s easy to find yourself with a particularly problematic page (I’m thinking of a very long list or if it depends on some slow external service) where streaming can help. Adding pagination or completely rethinking the approach is quite probably the proper solution but enabling streaming combined with some judicious calls to #flush could be enough to patch over the issue and give some breathing room for the real solution.

Using Phlex in Sinatra with phlex-sinatra

Phlex already works with Sinatra (and everything else) but its normal usage leaves you without access to Sinatra’s standard helper methods. That’s why I created phlex-sinatra which lets you use Sinatra’s url() helper from within Phlex (along with the rest of the usual helper methods available in a Sinatra action).

To enable the integration use the phlex method in your Sinatra action and pass an instance of the Phlex view (instead of using .call to get its output):

get '/foo' do
  phlex MyView.new
end

You can now use Sinatra’s url() helper method directly and its other methods (params, request, etc) via the helpers proxy:

class MyView < Phlex::HTML
  def template
    h1 { 'Phlex / Sinatra integration' }
    p {
      a(href: url('/foo', false)) { 'link to foo' }
    }
    pre { helpers.params.inspect }
  end
end

Why?

It might not seem obvious at first why you’d use url() at all given that you mostly just pass the string you want to output 🤷🏻‍♂️ but I hit the issue immediately when I switched to Phlex in my Wordle results Sinatra/Parklife microsite hosted on GitHub Pages.

One of the main features of using Parklife is that your development flow remains completely unchanged. In development you start the server as usual which means the app is almost certainly served from the root /, but if the static site is hosted as a GitHub Pages repository site it’ll be served from /my-repository-name – which means all your links will be broken in production! It’s incredibly frustrating but luckily easily fixed.

Step 1 is to use Sinatra’s url() helper method wherever you need a URL (the false second argument means the scheme/host isn’t included):

link(href: url('/app.css', false), rel: 'stylesheet', type: 'text/css')

Step 2, configure a Parklife base:

Parklife.application.config.base = '/wordle'

It’s also possible to pass --base at build-time, in fact if you used Parklife to generate a GitHub Actions workflow (parklife init --github-pages) then it’s already configured to fetch your GitHub Pages site URL – whether it’s a custom domain or a standard repository site – and pass it to the build script so you won’t need to manually configure it as above.

Step 3 (profit?). The result is that when Parklife generates the static build Sinatra will know to serve the site from the /wordle subpath and will include the prefix on all url()-generated URLs:

<link href="/wordle/app.css" rel="stylesheet" type="text/css">

Another main reason to use the url() helper is to generate a full URL – for instance from within a feed or for an og:image social media preview link. In this case don’t pass the false second argument (it defaults to true) and the full URL will be generated. Once again you’ll need to configure Parklife with the correct base but once again it’s already taken care of if you generated the GitHub Actions workflow with parklife init --github-pages.

My Wordle results, a Sinatra/Parklife app

Like many others last year I fell into a daily Wordle routine – I also collected the results. It’s taken a while but I’ve turned the data into a microsite of my Wordle results. It’s a Sinatra/Parklife app and a good (albeit tiny) example of using Parklife in the wild showing just how incredibly easy it is to take a standard Sinatra app and turn it into a static production build.

Whilst Ruby and its wealth of web libraries make it easy to create a web site the question of deployment isn’t as simple as it used to be. Back when Heroku had a free plan it would have been a prime choice for a little app like this and even though the content is essentially static it would still be a good match, but $60/year is enough of a nudge to reconsider whether essentially static should be actually static. I suspect this is a common situation.

The site itself is custom content and code that wouldn’t easily be squeezed into a more traditional blogging engine which is one of the reasons I think it’s a good example of why you should use Parklife and demonstrates the space that Parklife fills in the Ruby world of static sites.

In the past I’ve generated a number of custom static sites with Ruby, each time getting to know ERB and each one resulting in its own unique build process using Rake, Make, or some other bunch of scripts to generate HTML. They all worked fine and were satisfying to build but it’s not a sustainable, repeatable approach and it isn’t suitable for everyone. Parklife completely changes the landscape in this regard because it allows you to use any of the great existing frameworks you already know and lets you follow the same familiar approach as all your other Ruby apps – did I mention your preferred development flow remains completely unchanged.

My Wordle results are stored in a text file (currently 467 results, 2924 lines) that’s parsed into Result objects and served by a Sinatra app (a single route). At first I was surprised just how large the HTML was (its file size) and made a scattering of changes in an attempt to reduce it before finally switching to Phlex which doesn’t output additional whitespace (you could say it uglifies by default…). The final piece was to add Parklife and run parklife init --sinatra --github-pages to generate everything required to turn the app into a static site including a GitHub Actions workflow to build and deploy to GitHub Pages. Oh and the repo is public on GitHub.

Hopefully this example will encourage you to avoid dependency hell and use Ruby for your next static site.

Introducing Parklife

Parklife turns any Rack app (Rails, Sinatra, Hanami, Roda, Camping) into a static HTML build ready to be hosted on GitHub Pages, Netlify, Now, S3, or any other web server.

The great thing is that your development flow remains completely unchanged – keep working with the frameworks you already know and love and all those other gems you favour, keep running the usual development server, and keep writing unit and browser tests. Then when it comes to production, instead of deploying and managing a server-side Ruby app you generate a static build that can live indefinitely with no maintenance cost.

While Parklife works great with Rails – this site is a 15+ year old Rails app using SQLite/Paperclip/Sprockets+Sass/Parklife and hosted on Netlify – where I’ve really felt its impact is with Sinatra. Now you can use Sinatra’s renowned rapid and minimal server-side development flow to build a static production site – I feel like it’s fully unlocked Sinatra’s microbenefits and installed it in its rightful place as monarch of the microframeworks. So now there’s no reason not to use Ruby for those little ad hoc microsites that might otherwise have ended up using some other complicated technology – or maybe even not be created at all.

Parklife doesn’t start an actual web server and instead interfaces directly with your app via Rack by sending mock HTTP requests and writing the response body to disk – this is what allows it to work with any Rack-compatible framework. It can also detect and follow links to crawl an entire site so you can often get away with only configuring a starting root route.

It’s easy to add Parklife to your app, start by installing the gem and then run parklife init --sinatra --github-pages to generate a starter Parkfile configuration file (tailored for a Sinatra app), a build script, and a full GitHub Actions workflow to generate and deploy your site to GitHub Pages whenever you push to the main branch. It’s also not a one-way trip because at any point in the future you can choose to set sail and return to a life on the server-side seas – you can’t lose.

For me Parklife has somehow managed to roll back the decades to bring simplicity back to making websites. I’ve once again felt that je ne sais quoi immediacy of writing HTML in Dreamweaver and syncing it over FTP… Only this time I get to use today’s Ruby, today’s frameworks, and today’s CI and hosting providers.