DEV Community: Paul Oms

How to create a terminal simulation in the browser 👩‍💻🧑‍💻

Paul Oms — Tue, 31 Oct 2023 11:37:09 +0000

When demonstrating an API or similar service, your landing page should show how it works! You can easily use something like PrismJS to add syntax highlighting to your code snippets, which looks neat. But what about creating something a bit more compelling for the Hero unit of your landing page?

It needs to be simple and clear, and not necessarily syntactically correct, but it should look like a terminal, complete with a blinking cursor and simulated text entry. Something like this:

With the the help of TypedJS and TailwindCSS this is actually really easy.

Dependencies

Let's start by including TailwindCSS and Typed.js in our HTML <head> element:



<head>
    ...
    <script src="https://cdn.tailwindcss.com"></script>
    <script src="https://unpkg.com/typed.js@2.0.16/dist/typed.umd.js"></script>
</head>

Note that you might want to use a pre-processor/build step or similar in production, and load them async etc.

Our Terminal window

We'll start by creating a <div> element with a class of terminal-window and a <pre> element with a class of terminal-output:



<div class="terminal-window">
    <pre id="terminal-output"></pre>
</div>

Then let's style it a little with TailwindCSS, and add a close button, so it looks a bit like a terminal:



<div class="terminal-window mx-2 w-full xl:w-4/5 p-6 text-base sm:text-sm md:text-base rounded-md shadow-2xl bg-gray-800 max-h-80">
    <div class="relative">
        <div class="absolute -top-5 -right-5">
            <!-- Close button -->
            <button title="Close" class="text-gray-600 w-8 h-8 rounded-full flex items-center justify-center">
                <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" class="w-4 h-4"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path></svg>
            </button>
        </div>
    </div>
    <pre class="text-gray-300 whitespace-pre" id="terminal-output"></pre>
</div>

Sprinkle a bit of JavaScript

First initalize TypedJS, targeting terminal-output:



const typed = new Typed('#terminal-output', {
    strings: [textToType],
    typeSpeed: 20,
    loop: false,
    cursorChar: '_',
});

Next we'll write the text we want to show, it's a bit awkward but it's kind of like a mini Domain Specific Language:



const textToShow = "$ curl <span class=\"text-white\">https://app.mailpace.com/api/v1/send</span>\n -H MailPace-Server-Token: a3c4-efg6 \n -d {\n    from: awesome@developer.com,\n    to: important@users.com,\n    subject: Woah, MailPace Rocks!\n} \n\n`<span class=\"text-gray-500\">Sending...</span>`\n^250<span class=\"text-green-200\">✓ Email Sent!</span>";

^ followed by a number means to pause by that number of milliseconds, e.g. while simulating a network call
Anything wrapped in backticks is output from the terminal
\n is a line break
We we can embed <span> elements to give us basic syntax highlighting

Note that this curl example isn't working code, we just want to represent a simplified version for our viewers to understand what's going on. If we add all the pieces needed for it to work, it's not as clear what's going on.

Add some animation

Not strictly necessary, but let's add a little bounce when our users open the site, to kick start the typing:



<style>
    @keyframes softBounce {
        0%, 20%, 50%, 80%, 100% {
            transform: translateY(0);
        }
        40% {
            transform: translateY(-30px);
        }
        60% {
            transform: translateY(-5px);
        }
    }

    .terminal-window {
        animation: softBounce 1s ease-in;
    }
</style>

And we're done! Check out the working version here: https://mailpace.com

The trick to making console.log play nice with complex objects

Paul Oms — Thu, 21 Oct 2021 20:03:24 +0000

console.log is useful in a lot of situations (although there are usually better ways to debug if that's what you're doing).

In the browser console.log works well with objects, you can drill down as much as you need. But in Node.js, when you look at the output of a nested object, you'll often see this:

$ console.log({a: {b: { c: {d: {}}}}})

{ a: { b: { c: [Object] } } }

d: {} was replaced with [Object]. But why?

It's because the command line / terminal doesn't have a nice UI for drilling down, so Node attempts to print up to three levels deep. Beyond three levels it just prints [Object].

This is controlled by a variable in the node 'util' module, called depth, which defaults to 2. You can set it yourself here:

require('util').inspect.defaultOptions.depth = 0; // top level only, e.g.:
// { a: [Object] }
require('util').inspect.defaultOptions.depth = null; // print everything, e.g.: 
// {
//  a: { b: { c: { d: {} } } }
// }

It's not a great idea to change an underlying variable, as it might come back to bite later. So a cleaner way is to convert the JSON object to a string and log that. We can use node's built in JSON class and the stringify method:

complexObject = {a: {b: { c: {d: {}}}}}
console.log(JSON.stringify(complexObject, null, 2))

// {
//   "a": {
//     "b": {
//       "c": {
//         "d": {}
//       }
//     }
//   }
// }

Note that the 3rd parameter of JSON.stringify, Number 2, controls the number of spaces of indentation, and the 2nd parameter can be used to filter or adjust the objects and properties shown.

Now you can really see what's in those deep Objects.

What happens when you send an email to spam?

Paul Oms — Wed, 20 Oct 2021 16:07:36 +0000

TDLR: When you hit “Report spam”, this happens:

The offending email is moved to the spam folder
Spam detection systems are updated
If registered, an email complaint is sent through the FBL program in ARF format
The original sender should take action to prevent further spam

Read on for more details, the extended, original post is on the OhMySMTP blog here: https://blog.ohmysmtp.com/blog/what-happens-when-you-send-an-email-to-spam/

When you hit "Report Spam", at a minimum most email clients will place the email in a spam folder, and many providers will also update their spam detection models to prevent future spam.

That is helpful, but what about the person who sent the original email? If it genuinely is spam, then who cares? But perhaps the email was mis-categorized, or the sender wasn’t aware that it would be marked as spam. They need to know about spam reports to correct the issue.

There’s a solution: Feedback Loops (aka FBLs). FBLs are systems that email inbox providers have set up to send back details of any emails that have been marked as spam to the original sender's platform.

Email providers and high volume senders can register for the FBL with the email providers, and they will share these spam reports (also known as Complaints) to a Feedback email address. The sender can then review these and choose to stop sending to the addresses or take other action.

There are FBL programs at the big inbox providers (Google, Microsoft, Yahoo), and https://validity.com have consolidated many smaller systems. Reports are sent using the Abuse Reporting Format.

Going through the FBL process can take a long time (hours or days), and many senders/services are not registered in the first place.

Therefore to reduce spam in your inbox your best bet is to look out for unsubscribe links or use temporary email addresses and turn them off when done.

🤷‍♀️ The easiest way to monitor your app in production is email?

Paul Oms — Tue, 19 Oct 2021 11:37:16 +0000

It's really helpful to have a way to track what's going on with your application in production, things like: number of user sign ups, status of user accounts, number of X new database entries etc. Out of the box dashboards like Rails Admin are great but only go so far, eventually you will want significant customizations.

You could spend time coding a beautiful, custom dashboard to show you a summary of everything in real time. On top of coding it you'll spend time designing, testing, securing and deploying it. Plus digging into problems that pop up (what is monitoring your monitoring dashboard?). You might instead plug-in a 3rd party dashboard and query using that, which can be expensive and just as time consuming.

There's an easier way, which doesn't take away time from building your app or product: email. Specifically through email daily digests & notifications.

Compared to building a dashboard the advantages are numerous:

Faster to code
Doesn't consume any resources
Minimal DevOps required
Very easy to extend / customize
Reuses your existing tech stack
Almost no maintenance
Regular notifications (you won't forget to check the dashboard)
Everything is timestamped and archived by default

The main disadvantage is that it's not real time/interactive. But if you spot anything that requires a detailed drill down, you'll probably want to go in and do a detailed investigation through your app anyway.

Ultimately you should have several different tools monitoring your app to ensure things stay smooth e.g. external uptime monitors, exception trackers, log analysis, CPU/Memory usage tracking etc. This is an additional one you can add on for business logic monitoring

An example in Rails

To show you how easy this is, we'll create an example that sends the latest count of users every day to ourselves at the same time. You could extend this to send updates on anything tracked in your database (e.g. most popular article, unusual user behavior etc.)

Prerequisites:

A Rails 6+ app
A transactional email provider (e.g. Amazon SES, Postmark etc.) I recommend OhMySMTP and the associated Rails Gem: https://github.com/ohmysmtp/ohmysmtp-rails.

Email setup

Add this line to your application's Gemfile:

gem 'ohmysmtp-rails'

And then execute:

$ bundle

Configure your API Token

Retrieve your API token for your sending domain from OhMySMTP. You can find it under Organization -> Domain -> API Tokens

Open the credentials editor:

rails secret
rails credentials:edit

Then add your token:

ohmysmtp_api_token: "TOKEN_GOES_HERE"

Finally set OhMySMTP as your mailer in config/application.rb:

config.action_mailer.delivery_method = :ohmysmtp
config.action_mailer.ohmysmtp_settings = { api_token: Rails.application.credentials.ohmysmtp_api_token }

Setup our email template

We'll prepare an email template to send to ourselves or our team:

rails generate mailer monitoring

Which will create our mailer and folders to place our email templates in.

Modify the app/mailers/monitoring_mailer.rb file to include our daily notification and override our ApplicationMailer defaults:

class MonitoringMailer < ApplicationMailer
  def daily_update
    mail(to: "your-email-address@example.com", subject: "User Count Update")
  end
end

When this is called ActionMailer will look for a daily_update template to use. So let's go ahead and create that.

Create a file called daily_update.html.erb in app/views/monitoring_mailer with the email contents (note the placeholder for our User Count, count_of_users):

<!DOCTYPE html>
<html>
  <head>
    <meta content='text/html; charset=UTF-8' http-equiv='Content-Type' />
  </head>
  <body>
    <p>Total users: <%= count_of_users %></p>
  </body>
</html>

Our email is ready to go, now we need to calculate the count_of_users variable and trigger the email regularly.

Create a Rake Task

A rake task is basically script that can be called from another location. We'll put our simple monitoring logic and email trigger here.

TIP: For a more complex example in Rails put your monitoring logic in a Job, and call the job from the Rake task. Jobs can be run asynchronously by Sidekiq or another queue manager and are much more easily tested

rails generate task monitor_my_app

This will generate a file lib/tasks/monitor_my_app.rake - change the contents to the following (and here is where you'll make most customizations to fit your app):

namespace :monitor_my_app do
  task email_latest_stats: [:environment] do
     # Count number of new users
     @count_of_users = User.where("created_at > ?", 24.hours.ago).count

     ## Send the email with latest count
     MonitoringMailer.with(count_of_users: @count_of_users).daily_update.deliver_now
  end
end

Test it by running our Rake task

We can call this locally with:

rake monitor_my_app:email_latest_stats

Or if you're using Capistrano for deployments you can run this on production:

bundle exec cap production invoke:rake TASK=monitor_my_app:email_latest_stats

In your development environment an email should pop up in the browser, in production you'll see it arrive in your inbox in a couple of seconds.

Schedule it to run every day

Rake tasks can be called from Cron, so we'll use the Whenever Gem to automatically add our job to our Crontab during deployment, and keep our schedule in change control.

After setting up Whenever, add the following to your schedule.rb file:

every 1.days do
  rake "monitor_my_app:email_latest_stats"
end

That's it, after you deploy you'll get an email every day with the total number of users in your app. You can keep extending this with more concepts and daily digest emails - much much easier than building a custom dashboard!

How to add syntax highlighting to Code Snippets on your website, app or blog

Paul Oms — Wed, 13 Oct 2021 08:14:32 +0000

Have you ever wondered how sites like Dev.to, programming blogs and landing pages (like https://ohmysmtp.com) show little snippets of code with nice syntax highlighting? Read on to find out how to set this up on your site.

Note that there are code screenshot sites like https://carbon.now.sh/ that will give you great little screenshots of your code. But these are mere .pngs, they're not accessible, searchable or copy & pasteable. That's NOT what we're going to do here, our output will be fully accessible and appear as text on the page.

Code syntax highlighting looks like magic, but the actual reality is less complex than you might think. Let's get started.

Dependencies

We're going to use PrismJS to do all the heavy lifting.

There are a couple of choices to bring it into your project. If you're already using a JS Bundler (e.g. esbuild or Webpack) you can setup the Babel Plugin for Prism. For our demonstration we'll do this the old, simple way, writing our HTML tags directly.

Start by heading over to https://prismjs.com/download.html and:

Choose languages you want to support (keep this as small as possible to reduce file size)
Pick a theme
Download the prism.js and prism.css files and place them in your project

Finally we include them in the HTML page. CSS goes in the <head> section and the JS can go at the end of the <body> tag.

Tip: Place the JS at the end of the <body> section to avoid delaying loading the rest of the page

<head>
    ...
    <link rel="stylesheet" href="prism.css">
</head>
<body>
    ...
    <script src="prism.js"></script>
</body>

Adding the Code snippets

Next we'll add the code snippets we want to highlight plain old <code> tags. For example:

<code>
   const variable = "Here's some JavaScript";
</code>

Refresh the page, and you'll just see the code unhighlighted, like this:

const variable = "Here's some JavaScript";

We need to tell Prism to highlight the code block and which language to use. To do this we'll add a HTML class to the code block, in this format: class="language-XXXXX" where XXXXX is the language, like this:

<code class="language-javascript">
   const variable = "Here's some JavaScript";
</code>

Finally we'll wrap everything in a <pre> tag. This will "Preserve" the formatting and indentation of our code block so we can display it exactly as it would appear in the editor.

<pre><code class="language-javascript">const variable = "Here's some JavaScript";</code></pre>

Note that I've removed the line breaks / whitespace (these are usually ignored by HTML parsers). This is a bit awkward to read in our editor, but it means the JavaScript will appear exactly as we want it when rendered by Prism:

const variable = "Here's some JavaScript";

How this works

Our original HTML consists of standard <code> blocks, which are generally used for code examples, so the browser kind of knows how to display these without highlighting.

The Prism JavaScript scans the page searching for code blocks with "language-XXXXX" tags, and when it finds them it treats these blocks as code that requires syntax highlighting.

Prism them applies the syntax highlighting by:

Breaking each known code string into individual language "tokens"
Wrapping them in <span> tags
Categorizing them into types of language token (e.g. operator, punctuation, string etc.) and labelling them

It does most of the work using Regular Expressions, which you can easily read through in the source (e.g. for JavaSript the rules are here: https://github.com/PrismJS/prism/blob/master/components/prism-javascript.js)

The prism.css rules then take care of the actual colouring. These RegExes and the implementation can be quite complex, but the concept is relatively simple.

That's it - easy to add, when you know how.

Verify Webhooks in Ruby on Rails with Public Private Key Crytography

Paul Oms — Tue, 05 Oct 2021 08:28:45 +0000

When we first launched OhMySMTP we chose Paddle as our Payments Provider, primarily because they handle all sales taxes and payment infrastructure globally. One of the things that took longer than it should have was ensuring that alerts (webhooks) received from paddle.com actually come from Paddle.

Luckily Paddle signs every request using Public Key Cryptography, and it works in a similar way to DKIM. Paddle creates a short signature, using a Private Key specific to our Paddle account, and includes it with every webhook sent from their system, which we can verify on our end using the Public Key (see https://developer.paddle.com/webhook-reference/verifying-webhooks for more details). Without this a nefarious actor might figure out your webhook endpoint and create a bunch of fake subscriptions/updates in your app.

This verification is great, and Paddle has ok docs on how to do it. But I couldn't get the paddle code examples working in the OhMySMTP Rails app without some frustrating trial and error, so here's an example of how you can implement Paddle webhook endpoints with verification in Ruby on Rails. Broadly this should apply to any language as well.

Dependencies

You'll need to ensure you have the following dependencies available in your Gemfile (OpenSSL and Base64 should already be in Rails):

php-serialize
openssl
base64

Code!

`app/controllers/api/paddle_controller.rb`

# A standard Rails API endpoint definition
class Api::PaddleController < ActionController::API
  # Ensure every request is validated, except when testing
  before_action :verify_webhook, unless: -> { ENV["RAILS_ENV"] == "test" }

  # Select the right method depending on the webhook sent by paddle, see full list here https://developer.paddle.com/webhook-reference/
  def paddle
    case params["alert_name"]
    when "subscription_created"
      subscription_created
    when "subscription_payment_succeeded"
      subscription_payment_success
    else
      render(
        json: { error: "alert_name #{params['alert_name']} does not match a known webhook / alert" },
        status: :not_found
      )
    end
  end

  def subscription_created
    # Application logic here (e.g. update user account)
  end

  def subscription_payment_success
    # Application logic here (e.g. update user account)
  end

  private

  # The actual verification takes place below
  def verify_webhook
    # Copy and paste from https://vendors.paddle.com/public-key
    # You should store this in an environment variable in a real app, and note the line breaks / formatting which must match exactly
    public_key = "-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----"

    # We take all the params available as JSON structure
    data = accept_all_params.as_json

    # Extract the signature itself to verify later
    signature = Base64.decode64(data["p_signature"])

    # Remove the unsigned params (the signature itself and additional params from Rails)
    data.delete("p_signature")
    data.delete("controller")
    data.delete("action")

    # Sort & serialize params to match the original way Paddle signs the request
    data.each { |key, value| data[key] = String(value) }
    params_sorted = data.sort_by { |key, _value| key }
    params_serialized = PHP.serialize(params_sorted, true)

    # Verify the params and respond with 403 if verification fails
    digest = OpenSSL::Digest.new("SHA1")
    pub_key = OpenSSL::PKey::RSA.new(public_key).public_key

    return head(403) unless pub_key.verify(digest, signature, params_serialized)
  end

  def accept_all_params
    # We do this because paddle has a p_signature, and if they add extra params in the future
    # we need to ensure the signature still validates

    params.permit!
  end
end

That's it - easy when you know how.

Free (MIT) Transactional HTML Email templates built using Tailwind CSS

Paul Oms — Tue, 28 Sep 2021 07:59:00 +0000

Today I'm releasing a set of free HTML Transactional Email Templates. Check them out here:

mailpace / templates

A set of gorgeous Transactional HTML Email Templates built on TailwindCSS

These templates are super cool because they're built using Tailwind CSS, and the repository contains all of the build tools required to use Tailwind in HTML emails, making sure they render correctly across different browsers & devices. This is all powered by Maizzle - which provides CSS post processing to embed Tailwind into an email and apply a bunch of HTML email best practices.

Oh and they support Dark Mode out of the box ;-)

Why Tailwind CSS?

Tailwind CSS gives you "utility classes" to use in your HTML such as p-48 (apply padding of 48px to all 4 sides of an element) or rotate-90 (rotate an element 90 degrees). You can use these utility classes to build almost anything in HTML, without touching CSS.

At first this seems a bit awkward, like you're inlining CSS inside your HTML, but after you get used to the syntax it makes adding styling to HTML pages extremely productive. You don't need to switch context to CSS and come up with class names or an informal class hierarchy. It's hard to state how much more productive you can be in Tailwind, but it really is a massive boost when you're building HTML apps (or email templates in this case!)

If you do want to make components (e.g. .btn) you can use the @apply CSS directive to bundle up styles into components and reuse them.

But how?

The included Maizzle configuration post-processes all of your HTML using various PostCSS plugins. In the end, you just write normal HTML with Tailwind and Maizzle takes care of building your HTML templates out, and spits them into the /dist directory when complete.

Easy!

Who can use them?

Anyone, for any reason. They're MIT licensed so feel free to do what you like with them.

What are Transactional Emails?

Transactional emails are automated emails sent on a one-time basis, typically triggered by a user interaction or system update in your website / app. They are usually sent to one person at a time, and contain important or actionable information for your service.

Typical transactional email types include account notifications, receipts, updates, password reset notifications, magic sign up links and many, many more.

DEV Community: Paul Oms

How to create a terminal simulation in the browser 👩‍💻🧑‍💻

Dependencies

Our Terminal window

Sprinkle a bit of JavaScript

Add some animation

The trick to making console.log play nice with complex objects

What happens when you send an email to spam?

🤷‍♀️ The easiest way to monitor your app in production is email?

An example in Rails

Email setup

Configure your API Token

Setup our email template

Create a Rake Task

Test it by running our Rake task

Schedule it to run every day

How to add syntax highlighting to Code Snippets on your website, app or blog

Dependencies

Adding the Code snippets

How this works

Verify Webhooks in Ruby on Rails with Public Private Key Crytography

Dependencies

Code!

app/controllers/api/paddle_controller.rb

Free (MIT) Transactional HTML Email templates built using Tailwind CSS

mailpace / templates

A set of gorgeous Transactional HTML Email Templates built on TailwindCSS

Why Tailwind CSS?

But how?

Who can use them?

What are Transactional Emails?

Want to send your transactional emails through an Independent 💪, privacy-focused 🕵️ and eco-friendly 🌱 provider?

`app/controllers/api/paddle_controller.rb`