DEV Community: Gabriel Chertok

Hotwire empty states with Alpine.js

Gabriel Chertok — Mon, 07 Feb 2022 21:49:38 +0000

As I work more with Hotwire, replacing small chunks of the UI instead of re/rendering the whole page, I start to lose some of the benefits I used to have. Empty states are one of such things you don't get if you change refresh actions for more discrete ones like append or remove.

Take a look at the following example. I have a list of items I want to display, and I want to show an empty state when there're no items.

This behavior is easy to achieve with regular Rails, but adding Turbo Frame features like removing or adding to the main frame loses that ability.

The initial render works fine because the whole page gets evaluated, but as Turbo takes control and submits the form we never get our empty state back. Here's the backend code that sends the append or delete messages back to Turbo.

class NodesController < ApplicationController
  def create
    @node = Node.new node_params
    if @node.save
      respond_to do |f|
        format.turbo_stream do
          render turbo_stream: turbo_stream.append(:nodes, @node)
        end
        format.html { redirect_to nodes_url }
      end
    else
      render :new, status: :unprocessable_entity
    end
  end

  def destroy
    @node = Node.find params[:id]
    if @node.destroy
      respond_to do |format|
        format.turbo_stream do
          render turbo_stream: turbo_stream.remove(@node)
        end
        format.html { redirect_to nodes_url }
      end
    else
      render :index, status: :unprocessable_entity
    end
  end
end

Update all-the-frames

This problem can be easy to fix, or at least to hack. We could tell the backend to replace the wrapping turbo frame instead of removing/adding stuff to it. Telling Turbo to do this is easy, but it feels a bit out of place, as it starts resembling a lot to Turbolinks, and we don't want that. We want to be very prescriptive about our updates. Here's how you can achieve that.

def create
  ...
  respond_to do |format|
    format.turbo_stream do
      render turbo_stream:
        turbo_stream.replace(:nodes, partial: "nodes/_collection", locals: {nodes: Node.all})
    end   
  end
  ...
end

def destroy
  ...
  respond_to do |format|
    format.turbo_stream do
      render turbo_stream:
        turbo_stream.replace(:nodes, partial: "nodes/_collection", locals: {nodes: Node.all})
    end   
  end
  ...
end

CSS solution

Another possible way of achieving the same behavior is with CSS. We can piggyback on the :empty pseudo-class and show a blank state using the content property. That's ok, but again a little hacky for my taste. Having a CSS rule probably won't cut it for screen readers, and it's also not very semantic.

#nodes:empty:after {
  content: "Add new nodes 👇";
  text-align: center;
}

#nodes:empty {
  min-height: 1rem;
}

<div class="grid grid-flow-row gap-4 w-full">
  <!-- Keeping the if/unless because rendering an empty array yields a blank space and breaks the :empty css selector --!>
  <%= turbo_frame_tag "nodes", class: "grid grid-flow-row gap-4 w-full" do %>
    <% unless nodes.empty? %>
      <%= render nodes %>
    <% end %>
  <% end %>
</div>

JS solution

So far, we haven't tried to build a solution with JS, and I think we need to roll up our sleeves and make one.

A little disclaimer: I'm not a fan of Stimulus. After years of writing reactive UIs with React, using the DOM imperative API feels odd. Most of the Stimulus code I see out there leaves the DOM manipulations up to you to write on instance methods. My experience is that manually updating the DOM on state changes is error-prone; that's why most UI frameworks choose some flavor of reactive programming.

There must be a way to write the last 5% of the features that Hotwire can't handle reactively, and it turns out that there is. Say hi to Alpine.js.

Alpine.js feels a lot like angularjs, but without the mess and probably with more modest ambitions. It uses directives to enhance your HTML.

The syntax is straightforward, and I don't think I can do better than Alpine.js docs explaining it. I'll throw here some snippets assuming the syntax is so easy that you'll understand it without needing to know Alpine.js.

Back to our empty state problem, here's what I want. A piece of data holding whether I need to show the blank state or not and a directive that shows/hides it based on such value.

Now, we only need to know when to recompute this variable. Maybe I can use some Turbo callbacks.

<div class="grid grid-flow-row gap-4 w-full"
  x-on:turbo:submit-end="zeroState = $el.querySelectorAll('#nodes turbo-frame').length === 0"
  x-data="{
    zeroState: <%= nodes.empty? ? 'true' : 'false' %>
  }"
  >
  <%= turbo_frame_tag "nodes", class: "grid grid-flow-row gap-4 w-full" do %>
    <%= render nodes %>
    <p x-show="zeroState" class="text-center">Add new nodes 👇</p>
  <% end %>
</div>

I thought hooking into Turbo events would allow me to recompute the property based on the DOM contents, but I was wrong. Turbo fires a turbo:submit-end when the form submission ends, but querying the DOM at this point will compute the wrong thing since DOM hasn't been updated yet.

Luckily, we have a standard web API that tells you when a piece of the DOM changes, Mutation Observer. We can use Mutation Observer to call us back when the DOM mutation has been applied, and the zeroState variable can be recomputed.

<div class="grid grid-flow-row gap-4 w-full"
  x-data="{
    observer: undefined,
    zeroState: <%= nodes.empty? ? 'true' : 'false' %>
  }"
  x-init="
    observer = new MutationObserver(() => {
      zeroState = $el.querySelectorAll('#nodes turbo-frame').length === 0
    })
    observer.observe($el, {
      childList: true,
      attributes: false,
      subtree: true,
    })
  "
  >
  <%= turbo_frame_tag "nodes", class: "grid grid-flow-row gap-4 w-full" do %>
    <%= render nodes %>
    <p x-show="zeroState" class="text-center">Add new nodes 👇</p>
  <% end %>
</div>

Perfect! This code nicely does the trick, but wait, it's not very reusable, and empty states will appear everywhere in my app. We could copy and paste this boilerplate around, but we can do a little better by creating a custom directive that avoids us writing all that horrible x-init directive every time.

Another problem with this code is that I haven't found a way to execute cleanup code when the HTML containing the directive goes away. This cleanup is important because otherwise, we will be adding multiple observers and never disconnecting them. Here's what we want our code to look like.

<div class="grid grid-flow-row gap-4 w-full"
  x-mutation-observer.child-list.subtree="zeroState = $el.querySelectorAll('#nodes turbo-frame').length === 0"
  x-data="{
    zeroState: <%= nodes.empty? ? 'true' : 'false' %>
  }"

  >
  <%= turbo_frame_tag "nodes", class: "grid grid-flow-row gap-4 w-full" do %>
    <%= render nodes %>
    <p x-show="zeroState" x-transition:enter.duration.500ms class="text-center">Add new nodes 👇</p>
  <% end %>
</div>

Creating directives in Alpine.js is an advanced topic, more so if you want to mess with the reactive part, we only want to hide some code behind the directive and execute some cleanup tasks when it is unmounted from the DOM, so ours should be easy to build. Here's all the code.

import "@hotwired/turbo-rails"
import "alpinejs"

document.addEventListener('alpine:init', () => {
  Alpine.directive("mutation-observer", (el, { expression, modifiers }, { evaluateLater, cleanup }) => {  
    let callback = evaluateLater(expression)

    let observer = new MutationObserver(() => {
      callback()
    })

    observer.observe(el, {
      childList: modifiers.includes("child-list"),
      attributes: modifiers.includes("attributes"),
      subtree: modifiers.includes("subtree"),
    })

    cleanup(() => {
      observer.disconnect()
    })
  })
})

In our directive, we want to evaluate the expression -the thing that gets passed to the HTML attribute- every time MutationObserver calls us back. For that reason, Alpine.js has an evaluateLater function that returns a function that evaluates the expression when called.

The modifiers are what gets sent to the directive after the dot. In our case, those are the params for the MutationObserver config object; this way, we can have a pleasant and expressive API.

Finally, a directive does have a way to clean up via the cleanup callback. We can use that to disconnect the observer instance.

Aaaand that's it, there's no more work to do. After registering the directive, it will be available as a built-in one. I added some transitions using Alpine.js x-transition directive to make add some animation for the empty state, and here's how it looks like.

CSS solution v2

Before wrapping up, I want to mention a better way of doing this that was pointed out by Facundo Espinosa, who was kind enough to proofread this post and give me this alternative which I think is better. Yes, better than the wall of code I just made you read; sorry for that 🙏.

CSS has the :only-child pseudo-class that gets applied when the element is the only child. With that in mind, we could just write something similar to this.

<div class="grid grid-flow-row gap-4 w-full">
  <%= turbo_frame_tag "nodes", class: "grid grid-flow-row gap-4 w-full" do %>
    <%= render nodes %>
    <p class="hidden only:block text-center">Add new nodes 👇</p>
  <% end %>
</div>

Still, learning Alpine.js and how to create a custom directive was fun, and I'm sure it will help me in the future.

🛡 Blitz Guard

Gabriel Chertok — Wed, 10 Feb 2021 13:33:09 +0000

This article was originally posted on Monolith Bias_ the technical blog of the Ingenious development team.

As great as Blitz is for developing full-stack applications, I still miss the batteries included feeling Ruby on Rails has. I know I can't compare a mature framework like Rails to Blitz that barely has a year old, but I certainly miss the "there must be a gem for that" feeling.

One of the things I miss the most when working on a web app is a centralized place to manage authorization. Authorization is the most common requirement a web app may have. While Blitz itself tries to address this issue with the $authorize method that's built-in on the session, it falls short when the authorization is dependent on data attributes; technically called attributes-based access control.

The good news is that Nico Torres, a friend and former Ingenious employee, created Blitz Guard, the API is close to RoR cancancan gem but adapted to work with Blitz.

Installation

With Blitz Guard latest release, you can execute the following:

$ blitz install ntgussoni/blitz-guard-recipe

This line uses the Blitz Guard recipe to install the library. Recipes are an excellent, guided way to install new software in your app. It lets library developers update your codebase without breaking it.

What's inside

Once installeed you'll end up with several new files. The most important one is app/guard/ability.ts. This file is the core of your authorization logic, and it will serve as a single source of truth, whether a user can or cannot do things in your app.

import db from "db"
import { GuardBuilder, PrismaModelsType } from "@blitz-guard/core"
import { GetShoppingCartInput } from "app/shoppingCarts/queries/getShoppingCart"

type ExtendedResourceTypes = PrismaModelsType<typeof db>

type ExtendedAbilityTypes = ""

const Guard = GuardBuilder<ExtendedResourceTypes, ExtendedAbilityTypes>(
  async (ctx, { can, cannot }) => {
    cannot("manage", "all")
    if (ctx.session.$isAuthorized()) {
      can("read", "shoppingCart", async ({ where }: GetShoppingCartInput) => {
        return where.userId === ctx.session.userId
      })
    }
  }
)

export default Guard

The ability file creates a Guard using the GuardBuilder function. The resulting guard will be executed on every authorized query or mutation.

For example, if we want to deny access to a shopping cart based on who's the owner. We can do something like this:

// app/guard/ability.ts

import { GetShoppingCartInput } from "app/shoppingCart/queries/getShoppingCart"
// ...

if (ctx.session.$isAuthorized()) {
  can("read", "shoppingCart", async ( { where }: GetShoppingCartInput ) => {
    return where.userId === ctx.session.userId;
  })
}

Notice GetShoppingCartInput is the same TS type that we use in the getShoppingCart query

The can (and cannot) methods have three parameters. The first is the action to be performed (either create, read, update, delete, or manage), the second is which Prisma schema object this guard applies to (it doesn't need to be Prisma dependent, you can extend it using the ExtendedResourceTypes), and the third is an async function that should resolve to a boolean.

On this third argument you can implement any logic you want -like querying the DB- to assert whether the logged-in user has permissions to perform the action on the specified resource. A more interesting example could be the following:

//...
if (ctx.session.$isAuthorized()) {
  can("read", "shoppingCart", async ( { where }: GetShoppingCartInput ) => {
    if(where.userId === ctx.session.userId) return true
    const count = await db.shoppingCartShare.count({ where: { userId: ctx.session.userId, shoppingCartId: where.id } })
    return count > 0
  })
}

☝️ Here we assert that the user is the shopping cart owner or that the cart has been shared with this user previously.

Authorizing functions

So far, so good, but changing the ability file will do nothing if we don't authorize our functions. Blitz Guard will intercept your functions call and execute the guard only if we wrap queries and mutations with the authorize method.

import { Ctx, NotFoundError } from "blitz"
import db, { Prisma } from "db"
import Guard from "app/guard/ability"

export type GetShoppingCartInput = Pick<Prisma.ShoppingCartFindFirstArgs, "where">

async function getShoppingCart({ where }: GetShoppingCartInput, ctx: Ctx) {
 ctx.session.$authorize()

 const cart = await db.shoppingCart.findFirst({ where })

 if (!cart) throw new NotFoundError()

 return cart
}

export default Guard.authorize("read", "shoppingCart", getShoppingCart)

The first two arguments of this function should look familiar because they are the same arguments can and cannot functions receive. The third argument is the function we want to wrap, and that will only be called if the guard criteria are met. Otherwise, you'll get a 403.

This step is easy to forget, more so when the Blitz generator default exports the generated function. To aid this, Blitz Guard installs a middleware that warns you (in development) about queries and mutations not wrapped by the Guard.authorize function.

Final words

Blitz Guard is still under heavy development, but I don't think the API will change a lot. It's a great option if you plan to develop an ambitious Blitz app by moving scattered business logic into a single place.

Submit forms without using re-captcha

Gabriel Chertok — Thu, 24 Sep 2020 14:02:03 +0000

If you ever had to put a form on a public page, you know bots will find it and send you "service offerings", newsletters, direct emails, and much more. That's exactly what happened the first time I deployed the Ingenious contact form.

Opening a gateway to an inbox is problematic because, like everything in security, attackers -spammers in this case- have all the time in the world, and they can afford to do it wrong a million times until they nail it.

To fix this problem, some developers use re-captcha, a tool that "[...]uses an advanced risk analysis engine and adaptive challenges to keep malicious software from engaging in abusive activities on your website" 🥱. In plain English it keeps bots away from your forms.

There are a lot of great wrappers depending on the technology you are using. At Ingenious, we use Next.js and deploy our website to Vercel. If I wanted, I could have implemented some re-captcha validation on our contact form with an already existing npm package, but the sole idea of adding a library for something that trivial didn't sound right.

Looking for alternatives, I learned about honeypots. Honeypots are additional inputs you put on a form to make bots think they are submitting correct info. The idea is to give the bot a honeypot field that looks legit and hide it with CSS from the users. On the backend, we can check if honeypot fields were submitted and discard that submission.

export default function ContactForm({ onSubmit }) {
  return (
    <div>
      <h1>Contact Us</h1>
      <form onSubmit={onSubmit}>
        {/* This is for the bot */}
        <div className="honey">
          <label htmlFor="name">Name</label>
          <input id="name" name="name" type="text" autoComplete="off" />
        </div>
        <div className="honey">
          <label htmlFor="email">Email</label>
          <input id="email" name="email" type="email" autoComplete="off" />
        </div>
        <div className="honey">
          <label htmlFor="message">Message</label>
          <textarea id="message" name="message" autoComplete="off"></textarea>
        </div>

        {/* This is for real users */}
        <div>
          <label htmlFor="name89jhbg2">Name</label>
          <input name="name89jhbg2" id="name89jhbg2" type="text" />
        </div>
        <div className="flex flex-col">
          <label htmlFor="email789miu82">Email</label>
          <input name="email789miu82" id="email789miu82" type="email" />
        </div>
        <div className="flex flex-col">
          <label htmlFor="message342cdssf3">Message</label>
          <textarea name="message342cdssf3" id="message342cdssf3"></textarea>
        </div>
        <button>Send</button>
      </form>
      <style jsx>{`
        .honey {
          display: none;
        }
      `}</style>
    </div>
  )
}

Another technique I've used is to delay the rendering of the form several seconds after the page itself is rendered. My thinking behind this is that bots may or may not execute JS -likely they do- but I don't think they will wait more than 3 or 4 seconds. On the other hand, users don't need to see the form until they are way down on the page -the contact form in our case is close to the bottom of the page. By the time user has scrolled to the bottom, the form will be loaded already.

When working with Next.js, you will use the next/dynamic package that's somehow similar to the React.lazy functionality. The idea is to dynamically import a module creating a new chunk. Next.js will then fetch the module at runtime.

Importing a module returns a promise that we can delay. In the case of Next.js, we need to ask for the module to be client-side only with ssr: false, otherwise it will end up on the statically generated page.

import dynamic from "next/dynamic";
import { delay } from "../utils";

const ContactForm = dynamic(
  () => import("../components/contact-form").then(delay(3000)),
  {
    ssr: false
  }
);

export default function IndexPage() {
  return (
    <>
      <ContactForm onSubmit={onSubmit} />
    </>
  );
}

Lastly, we can tell Next.js to use a placeholder component while loading the dynamically imported one.

import dynamic from "next/dynamic";
import { delay } from "../utils";

function ContactFormPlaceholder() {
  return <div>Nice Spinner</div>;
}

const ContactForm = dynamic(
  () => import("../components/contact-form").then(delay(3000)),
  {
    ssr: false,
    loading: () => <ContactFormPlaceholder />
  }
);

This technique may hurt SEO, but how many times we need SEO for a contact form? The whole point is to allow real users to submit the form, not bots, even GoogleBot.

Here's the full example

You can reload the codesandbox, and scroll down to the bottom to se the form placeholder before the actual form loads, and click the "Show hidden fields" checkbox to try submitting the form as a bot.

Blitz.js a fullstack framework for the serverless era

Gabriel Chertok — Fri, 04 Sep 2020 12:51:59 +0000

Earlier this year, in a previous article, I push back on going serverless. Not because I think serverless is bad, but because the current serverless trend involves some practices that I don't think are useful for 95% of the apps that get built out there.

If you want to detour here's the previous article 👇 I'll wait here drinking my 🧉.

My monolith doesn't fit in your serverless

Gabriel Chertok ・ Jul 28 '20

#serverless #javascript #ruby #monolith

👋 Welcome back! As I was saying, I still think the same way. I still feel we need full stack frameworks instead of 15 specialized tools that you can consume from a front-end, and I understand where this pressure of using the right tool for the job comes from, but sometimes a hammer is good enough.

Hopefully, today I can marry these two worlds. Benefiting from serverless infrastructure while developing with a full-stack framework, as if you were writing Django or Ruby on Rails. Let's explore Blitz.js.

Enter Blitz.js

Blitz.js is a full-stack framework adapted for the serverless era. It carries all the benefits of serverless ready frameworks like Next.js -it's built on top of it- while adopting features like a data layer or a set of reasonable defaults.

Blitz.js is built on top of Next.js supporting most, if not all, Next.js features such as React for the view layer, Server Side Rendering (SSR), Static Site Generation (SSG), and the new Incremental Site Generation (ISG), but I feel the exciting parts are in the differences.

Serverless era?

Currently, full-stack frameworks can't run on platforms like AWS lambda or Vercel. These platforms can support different languages like ruby, Java, or PHP, but the full-stack frameworks' programming model doesn't play nicely with the constraints FaaS exposes.

Blitz.js embraces the FaaS constraints. You have no controllers, but stateless functions that can be executed as a long-running nodejs process or invoked as a lambda function.

Typescript

By default, Blitz.js wants you to use Typescript: you can opt-out, but I wouldn't recommend it. TypeScript is a solid language, and the framework generators and all the internals are written in this language.

Code organization

While Next.js doesn't hold too many opinions, maybe non outside how to do routing, Blitz.js does.

First, it encourages you to group files by functionality and not by role. If you have worked with a full-stack framework before, you know a big part of the framework's responsibility is to make these decisions for you.

├── app
│   ├── components
│   ├── layouts
│   ├── pages
│   │   ├── _app.tsx
│   │   ├── _document.tsx
│   │   └── index.tsx
│   ├── products
│   │   ├── components
│   │   │   └── ProductForm.tsx
│   │   ├── mutations
│   │   │   ├── createProduct.ts
│   │   │   ├── deleteProduct.ts
│   │   │   └── updateProduct.ts
│   │   ├── pages
│   │   │   └── products
│   │   └── queries
│   │       ├── getProduct.ts
│   │       └── getProducts.ts
│   └── queries
│       └── getReferer.ts
...

Routes

Here you see how products and app have both a pages directory. At runtime, all these routes are smashed together.

Queries & mutations

Besides pages, we see other types of files, such as queries and mutations. Let's explain those.

Queries and mutations are what you would expect, a way to query and store data from/to your database. While it's not restricted to the DB layer, it's probably the most common scenario.

Blitz.js uses Prisma 2, a framework to abstract the interactions with the database, and it's used like this:

import db from "db"

type GetCompaniesInput = {
  where?: FindManyCompanyArgs["where"]
}

export default async function getCompanies(
  { orderBy = { createdAt: "asc" } }: GetCompaniesInput,
  _ = {}
) {
  const companies = await db.company.findMany({
    orderBy,
  })
  return companies
}

Queries -and mutations- are not API endpoints, but regular TS functions that you can import from your components and call. This is a novel concept I haven't seen in any other frameworks, called Zero-API.

The idea behind the Zero-API is to allow you to call a function from a React component, while swapping that call at compile time for an API request. This results in a simpler programming model. Importing and calling vs. dealing with endpoints, with the added benefit of TS type checking inputs and results. The framework makes the heavy lift for us at build time.

export const Companies = () => {
  const [companies] = useQuery(getCompanies, {})
  return (
    <>
      <h1 className="font-bold text-4xl mb-8">Companies</h1>
      {companies.map((company) => {
        return <Company key={company.id} {...company} />
      })}
    </>
  )
}

Queries are called from the front-end with a useQuery hook. For mutations, no hook is needed you can just await the mutation response. Also, types are carried over from the hook to your variables.

Prisma 2

We talked about Prisma 2 when discussing queries and mutations, but it deserves a bit more explanation. At its core, Prisma is a set of packages that allows you to interact with relational databases using node or TypeScript.

If you choose TypeScript as Blitz does this, you get complete type safety for your models and DB operations, since Prisma will generate not only model types but types for querying and mutating the resource.

The way Prisma works is by having a schema file with a custom DSL. This schema is similar to the one you can find in Rails, but instead of being the result of applying migrations it operates as the source of truth, and migrations are generated from this file.

datasource db {
  provider = ["sqlite", "postgres"]
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

// --------------------------------------

model Company {
  id               Int      @default(autoincrement()) @id
  createdAt        DateTime @default(now())
  updatedAt        DateTime @updatedAt
  name             String
  description      String
  logo             String
  url              String   @default("")
  hasOffices       Boolean
  allowsFullRemote Boolean
}

After you run the blitz db migrate command, Prisma will generate a migration -a snapshot of the actual schema- and a Prisma client. A Prisma client is the package we use to interact with the DB and has the generated types for our schema.

CLI

Most of the things I talked about here can be created though the Blitz CLI. Currently, it has almost everything you need to start working with the framework such as blitz new {PROJECT NAME} or blitz generate to generate models, scaffolds pages and more, as well as the blitz db command to interact with Prisma using the same CLI.

Final words

There are many more things I wish I had covered in this review, such as the new upcoming seed command, the built-in authentication or the recipes.

I will be writing more about Blitz since I'm using it to rebuild remote.uy, so hopefully, I can cover more ground and learn since I'm not an expert on the subject, and the framework is rapidly evolving.

If you liked the framework, give it a try, and join the Slack community where most of the action takes place.

Liked the post? Shout out to Gustavo, Franco, Pepe, and Ruben that helped me edit and refine this article.

Avoid JIRA like the plague

Gabriel Chertok — Tue, 18 Aug 2020 18:51:00 +0000

Photo by Lucas Rosin on Unsplash

It's 2020, and JIRA doesn't allow you to archive projects, nor to export them, nor having feature parity with his own on-premises version. It's pretty clear. I dislike the tool, but these are not the main reasons we should avoid using it.

I work at a software development agency that executes projects for clients, mostly in the healthcare industry. We use JIRA a lot, including reporting, sprint planning, backlog grooming, addons, plugins, etc., and it has served us well all these years. But as we grew as a team, and as we seek perfection in how we execute projects I realized that the mere nature of the tool, this is, being prepared to work on small, discrete pieces of information (call them tickets, stories, bugs, etc.) is the very thing that slows us down.

What's JIRA

When using a tool, it's essential to understand what it's optimized for. For me, JIRA is optimized for chunking features into smaller pieces, relating them together, and keeping a log of who did what when. This is great when you have something to chunk, but most often than not, there's nothing to chunk yet.

We use JIRA -or any similar software- before understanding what to do. I've seen projects without any documentation, but hundreds of tasks on a board. You may think it's not the tool's fault, but the leader's for adding such tasks before knowing what to build, I'll argue that those leaders were left with a tool that his sole input are tickets, so they figured their job was to feed it with lots of them.

What's the problem with it

The tools we use shape how we work, and it turns out that we don't need a ticketing system, or at least, we don't need it for starting a project. I'll argue that we don't even need it for executing it.

To develop better software aligned with our clients' and users' requirements, we must understand their needs and use tools that favor the narrative. A tool that puts everybody in context and describes intentions. We need software that's able to tell a story instead of dividing it.

I feel so much time is wasted in ticketing. Bookkeeping, triaging and answering questions that at the end, the team is left only with fragmented pieces of reality and, too often, contradictory ones.

Being required to write a story that provides context and communicates the intention for feature X is much harder than creating 20 tickets with incomplete and contradictory ideas, and then, leaving the engineers to figure out the rest. With luck, they will figure out before writing the code, most of the time not. But that's ok, we can always create more tickets now with a better understanding of the world.

What to do then

I prefer to specify context-aware features that tell a story and illustrates the intention instead of splitting a feature into multiple tasks early in the process.

It requires more dedication from product managers, more writing, and thinking profoundly and upfront about the problems that need to be solved. Engineers also dislike the idea of not having everything arranged in tickets, but rather a massive piece of text that describes the problem instead of the steps to solve it.

Why doing something that everyone thinks it's worst? Well...when choosing to tell instead of splitting the problem, we are creating a more cohesive story, that makes sense as a whole, and it challenges itself as well. All this doesn't happen with tickets, they are artificial boundaries.

How to do it

I'm starting to write long-form feature definitions in Notion -I'm also writing this post in Notion-. Being deliberately slow at writing them and letting the concepts sink for more than a couple of days before making it available to the team. I try to be very explicit about the context and what's the takeaway for the user.

Only after this exercise I chunk the work -or let the engineers chunk it themselves- with a Notion inline database inside the feature definition, so devs can move things around. Still, this database is always constrained to the main feature description, you cannot look at one without looking at the other.

So far it works for me, and for the handful of people trying it, but my goal is to be able to make the switch out of JIRA, most importantly, out of the ticketing mindset. Yes, I lose advanced reporting, and yes, it requires more discipline from everybody in the team, but the gains are higher. Product managers stop splitting things early on and default to telling a story, engineers, on the other hand, are tasked with understanding the story and only then break them as they see fit.

Hope you liked it, and please let's discuss 👇

Thanks to Gabo, Masse, Gustavo, and Fadi for reviewing the post and helping me organize these ideas.

My monolith doesn't fit in your serverless

Gabriel Chertok — Tue, 28 Jul 2020 18:59:54 +0000

Serverless is the future, no doubts about that, and I love the model. For a small agency like Ingenious it helps us reduce costs and allow us to forget about infrastructure.

As cool as serverless is, I found myself always needing to go an extra mile to deploy a complete solution, and it's not for the lack of tools. I have come to the conclusion that the problems I'm tasked to solve are tricky to get right using a serverless approach. Here's my take on why not serverles-all-the-things.

What's serverless?

First, let's scope what we say when we speak about serverless. A definition I like -that may be incomplete- is the following: "Serverless is the ability to scale up, but also to scale down to 0".

I would add that typically serverless comes in the flavor of specialized services. For example, if you do a serverless app to store and retrieve things from a database, you may need at least functions, datastore, and authentication services. Probably also some background job processing, CDNs, etc.

In theory, this sounds amazing, having all these discrete parts that do only one thing, and one thing well sounds appealing. I used to think serverless would solve most of our problems and that we will be able to write the frontend and author some functions to glue the different services together.

I don't think that anymore

Sadly, I don't think that's the case. At least not for the apps I build, and I would argue that's also the case for many of you.

Stitching services together sounds excellent in theory, but it has its own complexity. I'll try breaking down a list.

Lack of conventions

When developing a monolith, either RoR, Laravel, Django, or any other tool, you have a common way of modeling the problems, and this philosophy sticks during the development process. I think I would know how to use Rails ActionMailbox even if I never used it in the past, the framework is coherent and I know what to expect.

This doesn't happen when you use Service A for one thing and Service B for another. There's some extra work your brain needs to do when moving between specialized services.

Event-driven programming is hard

At the very core, whenever you need to use two services together and complement some missing functionality with a lambda function, you are doing event driven programming. This is, an action performed in service A may trigger a function to execute and impact your datastore, or to send an email, etc.

This model is hard to follow, things end up in a database, or in a queue without apparent connection. Similar to what happens on a monolith with model callbacks where you start getting effects that do not follow an evident cause.

Conclusion: How to decide

As usual, it depends. When the endeavor is huge, and you are building an app that needs to scale rapidly and painlessly, I think you should definitely consider serverless. Here service orchestration costs are less than what the services itself will offer in terms of scalability, reliability, etc.

The same is true when tradeoffs are minimal. Imagine a small website like Ingenious's website or a marketing site. Those have not that many moving pieces, so I think it's ok to liberate myself from thinking about the infrastructure.

But, here's the catch. Most of the apps we develop, and when I say we, I mean, most of the people I know that work on the industry -sorry, I don't have any friends at Google 🤷- are in an uncomfortable middle ground.

Their app is probably not that big that needs to scale to infinity. Neither is so small that you can hold the architecture in your head all the time.

Most of the apps I've worked on are fine running on Heroku dynos or having a few powerful DO boxes. Yeah, that may be a bit expensive, and I'm sure you can cut the bill by 50% if using serverless, but is it really necessary? What things are you trading off by doing that?

Too many times, I end up answering that it isn't worth changing. I may be getting old 👴🧉, but I prefer to be in control and to keep the same conventions thru my app even if I need to pay a bit more.

With that being said, I also think this will change rapidly. Both, technologies, and serverless services will end up providing full-stack frameworks that will mix the best of both worlds. I think Blitz.js heads in that direction, and it will be interesting to see how it evolves.

For now, I'm sticking with monoliths and plain-old-servers for the apps I need to maintain, but hopefully not for too long.

Technology-wise, where is Ingenious going?

Gabriel Chertok — Tue, 14 Jul 2020 01:29:19 +0000

Disclaimer

The following is a post I wrote for the Ingenious team a few weeks ago. I wanted to give some guidance about what to expect in terms of tech decisions in the future. It is not that we haven't thought about this before, but the last time we did it was some years ago, and from there, we kept going with the flow. I took a step back and tried putting what I currently believe in this post.

We are a software development agency that helps to build Healthcare products using our own approach "Behavioral Design" based on Behavioral Economics concepts. For the sake of this post, you can think of Ingenious as a regular boutique development agency.

Original post

When I joined Ingenious, more than 6 years ago, the idea was to help the team shifting the technology foundations of the company, I ended up doing much more, but I want to focus on the technology side of things today. Back then, Ingenious was not Ingenious, but Ingenious Softworks and I found an amazing team of experienced .net developers.

Slowly, as I started to bring my own ideas and experiences to the table, I was able to convince some of you that open source software was the right choice and a smart move if what we were going to build were web applications. I brought my own years of Ruby on Rails experience and my passion for JavaScript, and from there it took off.

Later, when the whole JS ecosystem blew off, we were already in a position to take advantage of it. We picked Ember as a frontend framework for My Fertility -they still use it- we also picked React for some early projects for Denver Health. It was official, we were making Single Page Applications, we still do them, but more importantly, we embraced the UI component model.

Timeline

While this seems natural, at one point we decided -we Ingenious, we the developer community, this is a big we- that to be able to develop application UIs using components -this is, mixing together HTML, JS, and CSS in a single unit- it was necessary to create a new, separate application.

To a certain degree, this makes sense, when React -and every other framework came out- SSR was an optimization left out for later, for example, there was no way in Ember to do SSR when it first came out, neither React had one so it made sense to create its own application and communicate using JSON. Also, globally there was -still is- a trend around technology specialization. We never shared that vision that says that if I know the ins and outs of a certain technology, then I can be more productive with it and do more work in less time. I always thought that to deliver a feature, one should be able to work on both ends, even if that work is slower, it would be complete, and I hold to that belief today.

All those reasons, and probably many more lead us to believe we needed to choose between a single monolith that treats complex views as second class citizens, or specialized apps that can leverage React, or Ember, or Vue, but that cannot co-exist in that monolith, and that's simply not true. It was not true back when we made these choices, and it's definitely not true today.

In most of the cases, having multiple apps hurts productivity more than finding a way around the monolith and enhance it with JS. Having multiple apps generates a REST contract that needs to be held true for both ends, it creates the need to keep both apps in sync, it doesn't produce faster results, it generates stagnation and slower cycles since now there are at least two moving pieces, two codebases, two apps that can go down, two everything, that's 100% more problems.

That's not to say sometimes you need two applications, sometimes splitting is required, even mandatory -thinking about mobile apps here- and there's no way around those scenarios, but when there is, we should think things carefully.

In retrospective, I should have revised my decisions more carefully, I should have challenged the status quo more. Luckily, I have you that did a fantastic job regardless of those decisions.

Moving On

Moving on, we should think if the benefits of doing what everybody else is doing will benefit the project, will help the team, but most importantly, if it will benefit the client.

My intention is not to categorically ban SPAs and React or Angular or Ember at the company, but to give you the chance to think about that part of the architecture more in-depth. This is me telling you that you can choose not to go with our standard approach, and this is me telling you that our standard approach may someday be not standard at all.

Alternatives

You may be thinking, ok if we should consider sticking with the monolith more closely how should we build UIs from now on, do we go back and ditch the component model? No, I don't want to do that either, I think that's a step back.

Luckily, other options put things in a nice middle ground. Some are more appealing, some feel dated, and some are new tech that we may consider using in the future.

Here I list some options I've found for the current technologies we use, there should be plenty more that I'm missing.

Ruby on Rails

Rails has been our de-facto way for building backends at the company, and I think it will serve us for many more years. It has excellent features, and it's battle-tested. I think it also worth mention that Rails can do React or Angular, or Vue and some solutions even allow SSR and re-hydration.

Here's a list of things that we may reach out in the future:

Rails Webpacker (does React, Vue, Elm, Svelte, Angular)
React Rails (does SSR)
Stimulus + Turbolinks
Stimulus + Stimulus Reflect
Stimulus + Turbolinks + NEW MAGIC 👇

Phoenix

Phoenix is a Rails like framework for the Elixir programming language. I won't enumerate the benefits of the functional approach elixir has, or how good the Erlang VM is, all that you can read elsewhere. The only thing that strikes me as I rethink best practices is that you can create nice interactive applications with it, you can mix presentation and behavior -ala React components- in structures called LiveComponents without needing to split your app.

How can Phoenix do this? It's not important for the sake of this discussion. The important thing is that you can create reusable components as monolith first-class citizens. The tradeoff is learning a new language with new paradigms, this is a tradeoff that we may be willing to do if we stick true to our previous learnings of having less moving pieces.

Blitz.js

Blitz is a full-stack framework inspired by Ruby on Rails but written in React. It's based on Next.js and it can deploy itself as a fullstack application with a long process serving the app or in a serverless environment like AWS lambda or Vercel.

The promise is to keep writing React components, import server side code functions and call them as if they were in the client. Blitz takes care of translating that to API calls.

What's next

Ok, so this is all nice, but it's missing an actionable item, what to do next? I realize that you need certainty, not the half baked solution I just gave some paragraphs ago. Sadly, there's no silver bullet for developing software as there's no silver bullet that will fit all the projects we do at the company.

From Qt apps that read CT scans to huge backends in Rails to more serverless oriented architectures we have covered a lot of ground in software development, and we will continue to do so in the best way we can, and similar to today's post there will be new ones enumerating things we believed were right but ended up being wrong decisions.

For the moment, my current thinking is to try hard not to break the monolith unless it's absolutely necessary.

No much more to say other than, stay current, and stay focused in the tech that better solves our problems; this sometimes means no to jump in the next hype bandwagon.

-Cherta

Generate authorized-short-living URLs in rails

Gabriel Chertok — Sat, 10 Mar 2018 16:06:44 +0000

Last week I got a small task for a project my team is working on. I don’t usually code that much lately, but this one seemed like a simple and straightforward one.

The problem was straightforward, allow clients to download an on-the-fly generated file (a report) from our React frontend. As trivial as it may sound some interesting caveats made this problem not trivial at all.

As you know, SPAs communicate with the backend using AJAX and most of the time authentication/authorization is done via some kind of header information. At Ingenious we use JWT a lot, and we love it.

For our app, users need to be authorized and authenticated to get the report but streaming a file as a response of an AJAX request only works for Chrome, all the other browsers ignore the response and don't pop up the save file dialog.

The problem is now evident:

How to stream contents to the client with AJAX when there are authentication headers involved.

Start digging, stop digging

As usual, I googled "js generate file from stream" because I thought it was the easiest solution, just grab what I already have working for Chrome and do the extra mile to make it work for all the other browsers.

Maybe there’s even an npm package for that, but I quickly realized that this was not the right choice and that throwing npm packages to the problem won’t solve it, quite the opposite, it will make it difficult to read and error-prone.

Rethinking the problem

My problem was not to stream contents via AJAX and generate a file out of that content but actually allow clients to download a file (which happens to be created on the fly) without compromising the app security, i.e., without opening a resource to the whole internet.

With this new objective in mind, I re-imagined the file download as a two-step process.

What if the client app request the document to be created and as the response, it gets a short-living URL for that resource.

The idea was to:

Request a file "creation" from React and get back a signed short-living URL. This is an authenticated request.
Using this URL, I can request the report in a new window without any extra headers (and thus without the usual authorization I use for my web app).

The key was to generate a URL on step 1 that carries a token on the query string with an expiration date I can check on the “open” endpoint (step 2). So I looked for a solution that allows me to sign data and make it expire after X amount of time and guess what, JWT does precisely that.

The only key difference is that I had to create a token and send it on a query string due to the impossibility to send headers when doing a window.open.

Show me the code

The previous code the app had was quite simple, we made an AJAX request and streamed with send_data the contents of the file. Authorization / Authentication is done via Pundit / Knock on a before_action hook.

This wasn't working for browsers other than Chrome so I split the process, first create a report URL that will live for 30 seconds and serve the file on that new URL.

We added a create method to the controller. This method will be in charge of creating a short living URL using a signed JWT token that will expire in 30 seconds from now, I also encode the user id that's requesting the resource.

The client will get a JSON object similar to this:{url: "https://domain.com/reports/report_type?token=encryptedtoken"}.

The show changes a bit, it skips the authentication and, the first thing it does is to decode the JWT token with JWT.decode. JWT.decode would throw a JWT::ExpiredSignature if the token expired. I can then rescue from that error and return a 403 to my users if needed. I can also rescue from JWT::DecodeError in case no token is given for example.

If everything passes then, I know the URL was signed by me and that it's within the exp time I set on the create method. I can later override the pundit_user and call my authorization method for an extra security layer.

Conclusion

With this simple idea we can have authenticated, short-living URLs with an approach that's flexible enough to avoid rewrite huge parts of our client app. I hope you like the idea.

Are you looking for a passionate team that can help you envision, design, and build amazing products? Drop us a line.

About Ingenious

Ingenious is a distributed product design and software development agency with offices in Montevideo, Uruguay, and Denver, Colorado, and a team distributed in more than five countries. We create products and build software that people want to use for challenging industry segments like healthcare, education, and government.