DEV Community: Ricardo García Vega

Embracing agentic coding

Ricardo García Vega — Sun, 18 Jan 2026 08:53:48 +0000

It’s been more than four years since I last posted here. I never planned to stop
writing about Elixir or making tutorials for so long, but life got tough, and a
mix of challenges wore me out. I burned out and started to question everything.
Even so, there were good moments in those years, though I only noticed them after
hitting a low point and reaching out for help.

I want to get back to writing on this blog because I really enjoyed it.
There’s a lot more Elixir content out there now, and the Elixir community—and tech
in general—has changed a lot in the past four years. The biggest shift has been the
rise of AI. At first, I saw AI as a threat that could take my job. But after using it,
reading about it, and learning by doing, my perspective changed. Now, I see AI
as a tool that boosts my productivity and creativity.

With this new outlook, I wanted to share my recent experience using AI in my
daily work and personal projects. After four years away from the blog, I barely remembered
it was built with Next.js and had many outdated dependencies. My first job was
to migrate it to a Phoenix project. I’ve done migrations like this before, but
I didn’t want to spend too much time on it. Since it was the holiday season and
I was on vacation, I also wanted to focus on healthy activities and spending time
with family and friends. That’s why using AI seemed like the perfect fit.

Desired end state

To explain my goal, I had already done a similar migration for TalentoIT’s blog.
That project is a simple Phoenix LiveView app that uses NimblePublisher to pull markdown
files from a folder and build a list of post structs at compile time. There are
handy functions for accessing posts, and you only need a couple of live views to list
and display them. For my own site, I wanted the Phoenix version to look and feel like the current one,
but with the latest version of Tailwind. This meant moving all the Next.js components
to Phoenix components and switching from Tailwind 3 to 4. Once I knew what I wanted,
all that was left was to open the terminal and get started.

Preparing the new project

The first thing I did was to create a new, simple Phoenix application:

mix phx.new bigardone_dev --module BigardoneDev --no-dashboard --no-ecto --no-gettext --no-mailer

This generated the project scaffold and installed all the dependencies. My agentic
coding tool of choice is Claude Code, and to give it (or any other agentic tool)
valuable information about your project and its dependencies, I also added usage_rules
to the list of dependencies. This library gathers usage rules from both Elixir
and dependencies installed in your project into a file or files that you can
later reference in your coding agent of choice, so it has some basic guidance on how to
do specific stuff. As for today, Phoenix, Ecto, and many other popular libraries
support it, so I’ve been using it lately. But before generating the rules,
I started Claude Code and ran the /init command to generate a basic CLAUDE.md
file for the project, giving Claude some basic context. With the CLAUDE file in
place, I ran the following mix task to generate the usage rules:

mix usage_rules.sync CLAUDE.md --all --link-to-folder docs --link-style at

This command does two things:

It creates a bunch of Markdown files in the /docs folder with specific guidelines on using all supported libraries and basic Elixir features.
It updates CLAUDE.md by adding a new section that references all these files, so it knows where to find the information when needed.

With the setup complete, I was now ready to have Claude help me with the first task: a little cleaning.

A little of vibe coding

Instead of following the same agentic methodology I’ve been using for the last few months,
which I will describe in a bit, I decided to make Claude one-shot a simple task and check
how it went. The task was to remove all Daisy UI references from the project.
Since I wanted exactly the same style as the original version, I didn’t need it,
and Phoenix actually comes with a lot of predefined code regarding Daisy UI.
I jumped into Claude Code and typed the following prompt:

Remove all DaisyUI-related code from the project

Claude started doing its thing, and after a short time, it responded with the success message:

⏺ I've successfully removed all DaisyUI-related code from the project. Here's what was done:

  Files removed:
  - assets/vendor/daisyui.js
  - assets/vendor/daisyui-theme.js

  Files modified:

  1. assets/css/app.css - Removed daisyUI plugin imports and theme definitions
  2. lib/bigardone_dev_web/components/core_components.ex - Replaced all daisyUI classes with Tailwind CSS equivalents:
    - toast, alert, alert-info, alert-error → standard Tailwind positioning and color classes
    - btn, btn-primary, btn-soft → Tailwind button styles
    - checkbox, select, textarea, input, and their error variants → Tailwind form styles
    - table, table-zebra → Tailwind table styles
    - list, list-row, list-col-grow → Tailwind list styles
    - Updated moduledoc to remove daisyUI reference
  3. lib/bigardone_dev_web/components/layouts.ex - Replaced navbar, btn-ghost, btn-primary with Tailwind classes and removed the theme_toggle component
  4. lib/bigardone_dev_web/controllers/page_html/home.html.heex - Replaced badge, rounded-box, bg-base-*, text-base-content, fill-base-content classes with Tailwind equivalents and removed <Layouts.theme_toggle />
  5. lib/bigardone_dev_web/components/layouts/root.html.heex - Removed the theme toggle JavaScript
  6. CLAUDE.md - Removed daisyUI references from architecture overview and asset pipeline sections

  All tests pass, and the build compiles successfully.

The output looked accurate. After checking, I opened the browser, started the
Phoenix server, and looked for any errors. Everything worked fine—great!
Here’s the commit with all the changes. Next, since there was something else I
wanted to check that’s important for any LLM-related task, the current context usage.
So I ran /context to see how Claude’s context window was doing after the task:

> /context
  ⎿
      Context Usage
     ⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-opus-4-5-20251101 · 174k/200k tokens (87%)
     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛁ ⛁
     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   ⛁ System prompt: 3.1k tokens (1.6%)
     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   ⛁ System tools: 16.0k tokens (8.0%)
     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   ⛁ MCP tools: 14.4k tokens (7.2%)
     ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   ⛁ Custom agents: 481 tokens (0.2%)
     ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ ⛶ ⛶ ⛶ ⛶   ⛁ Memory files: 7.8k tokens (3.9%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝   ⛁ Messages: 87.3k tokens (43.7%)
     ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝   ⛶ Free space: 26k (12.9%)
     ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝   ⛝ Autocompact buffer: 45.0k tokens (22.5%)

This check showed it was already at 87%, so continuing with this session or using
the same method to migrate the whole app wasn’t a good idea.

A little context engineering

Nacho, the CTO at Timeline, the company I recently joined, has been guiding
the team to embrace AI and agentic coding to boost our creativity and productivity.
As he pointed out once, we like it or not, this is the reality we live in now,
and if we want to be full-stack engineers, working efficiently with AI is part of the equation,
just like having backend, frontend, or database skills. In one of his talks, he shared a great video with our team
about advanced context engineering for coding agents. It really stuck with me and
changed how I think about using coding agents. The main point is that you need to
pay close attention to the context you give the LLM and how you manage its context
window. If there’s not much space left, the LLM is more likely to make mistakes or
hallucinate. The video also explains a method for better managing context by using
sub-agents and purposefully compacting it. Instead of using something like /compact,
where you don’t have full control over what the agent keeps or removes, the speakers
suggest a different approach with three steps:

Research: In this step, you ask the agent to gather information to achieve a given task,understand the problem, and explain how the system currently works. The output is a Markdown file in a specific format that contains all key findings, code references, open questions the LLM might have, and related details. Once the file is created, you have to review it thoroughly and iterate on it, making any necessary changes to ensure it is as accurate as possible.
Planning: Once the research step is finished and the document is good enough, you start the planning phase. In this step, the LLM reads the research document and generates a step-by-step implementation plan for the changes to be made. Again, the output is another Markdown file containing the detailed implementation plan, which you have to review carefully and make any necessary changes.
Implementation: Once the implementation plan is as good as you want it to be, you give it to the LLM to execute, reviewing the changes as they are implemented and being ready for any issues it may encounter.

For each of the steps, there are some specific commands and agents that you can find
in HumanLayer’s repository. To maximize the context window efficiency, you have
to run each command in a fresh session, and each command uses the output of the
previous one as fresh context. Therefore, you have way more control over what information
the agent is going to use compared to using the /compact command.

What I like most about this approach is that it feels like working with another teammate.
This teammate helps me gather information, spot key points I might have missed,
and come up with alternative solutions to the problem. Also, because you need to
be careful with the documents from the first two steps, it’s easier to understand
both the problem and the solution before starting the implementation.
The method is flexible, too. Even if you don’t want the agent to do the coding,
you can still use the research and planning documents to share with your team in
a pull request and work on them together.

The research

I’ve been using this methodology for a few months, so I had all the commands and
agents in my ~/.claude folder. I jumped into the terminal, started Claude Code,
and typed the following:

/research_codebase I have the following Next.js blog in ~/projects/bigardone/bigardone.dev,
and another Phoenix blog using static content in ~/projects/bigardone/talento_it/talento_it_blog.
Create a research document to make this project behave like talento_it_blog, but with the layout, style, and
contents from the Next.js blog.

And the magic began:

⏺ I'll research all three codebases to understand how to combine talento_it_blog's static content approach with the Next.js blog's layout and content. Let me spawn parallel agents to explore each codebase.

⏺ 3 Explore agents finished (ctrl+o to expand)
   ├─ Explore current Phoenix project · 0 tool uses
   │  ⎿  Done
   ├─ Explore talento_it_blog static content · 0 tool uses
   │  ⎿  Done
   └─ Explore Next.js blog layout/content · 0 tool uses
      ⎿  Done
...
...
... (Shortened for brevity)

After a few minutes, it finished the research and generated the document:

⏺ Research Complete

  I've created a comprehensive research document at:
  thoughts/shared/research/2025-12-19_11-24-29_static-blog-migration.md

  Key Findings

  talento_it_blog Architecture (to replicate):
  - Uses NimblePublisher for compile-time static content from markdown files
  - Posts stored in /posts/ with YYYY-MM-DD-slug.md naming
  - Post struct with reading time calculation, categories, tags
  - LiveViews for home listing and post detail
  - Hot reload for markdown files in development
...
...
... (Shortened for brevity)

I opened the research file and read through it carefully. It looked good. It covered the
three projects and their key findings, like current technologies, dependencies,
and code structure. It also listed how many posts I had, their frontmatter format,
and the current UI layout, including colors and fonts. There was even a short
implementation plan and some open questions to tackle before moving forward.
After checking the context, there was still plenty of space left, so I asked it
to make a few changes here and there.

/context
  ⎿
      Context Usage
     ⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-opus-4-5-20251101 · 91k/200k tokens (46%)
     ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁
     ⛁ ⛁ ⛁ ⛁ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System prompt: 3.1k tokens (1.6%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 16.2k tokens (8.1%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Custom agents: 481 tokens (0.2%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Memory files: 7.8k tokens (3.9%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 18.5k tokens (9.3%)
     ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝   ⛶ Free space: 109k (54.4%)
     ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝   ⛝ Autocompact buffer: 45.0k tokens (22.5%)
     ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝

After making a few small changes, I was happy with the document and felt it was
good enough for the first version of the migration.

The implementation plan

With the research document ready, I started a new session in Claude Code and ran the following command:

/create_implementation_plan for thoughts/shared/research/2025-12-19_11-24-29_static-blog-migration.md

This is the most important part. By starting a new session with a fresh context
window and giving it the document we want to use, instead of using the previous
session’s cluttered context, we get a more accurate implementation plan.
After I hit enter, Claude Code got to work:

⏺ I'll read the research document you've referenced to understand what we're implementing.

⏺ Read(thoughts/shared/research/2025-12-19_11-24-29_static-blog-migration.md)
  ⎿  Read 460 lines

⏺ This is a comprehensive research document. Let me now spawn parallel research tasks to gather more context from the referenced codebases before creating the implementation plan.

⏺ Read(~/projects/bigardone/talento_it/talento_it_blog/lib/talento_it_blog.ex)
  ⎿  Read 49 lines

⏺ Read(~/projects/bigardone/talento_it/talento_it_blog/lib/talento_it_blog/post.ex)
  ⎿  Read 68 lines

⏺ Read(~/projects/bigardone/talento_it/talento_it_blog/lib/talento_it_blog_web/live/home_live.ex)
  ⎿  Read 74 lines
...
...
... (Shortened for brevity)

It started by reading a lot of files from the two existing projects, and asking
me about the open questions in the research document:

⏺ Based on my research of all three codebases, I have a comprehensive understanding of what needs to be done. Before I write the detailed implementation plan, I have a few questions to clarify:

  Questions that my research couldn't answer:

  1. Frontmatter format: The Next.js blog uses YAML frontmatter, while talento_it_blog uses Elixir map syntax. Should I:
    - Keep YAML and add yaml_elixir dependency (easier migration, less conversion work)
    - Convert all 100+ posts to Elixir map format (more consistent with Phoenix ecosystem)
  2. Scope for initial version: The research document lists several optional features. For the initial implementation, should I include:
    - Related posts section on post detail page?
    - Tag filtering on the blog listing page?
    - RSS feed?
  3. URL structure: The Next.js blog uses /blog/YYYY/MM/DD/slug. Should I keep this exact structure for SEO continuity, or simplify to /blog/:slug?

⏺ User answered Claude's questions:
  ⎿  · Which frontmatter format should we use for the markdown posts? → YAML (Recommended)
     · Which features should be included in the initial implementation? → Core only (Recommended)
     · What URL structure should we use for blog posts? → /blog/YYYY/MM/DD/slug (Recommended)

To keep things simple, I went with the recommended options. I wanted this to be
a quick migration with just the basics, and I could always add more features later.
After a few minutes, the implementation plan was ready to review. When I read it,
I decided to tweak it a bit and add automated browser testing with the Playwright MCP
server instead of the manual testing suggested in the plan. So, I started a new session and ran:

Continue with the implementation plan of thoughts/shared/plans/static-blog-migration.md, and update it to use the playwright mcp for visual verifications

This made Claude Code read the current implementation plan and make the necessary
updates to the success criteria sections:

⏺ I'll read the existing plan file to understand what needs to be updated.

⏺ Read(thoughts/shared/plans/static-blog-migration.md)
  ⎿  Read 996 lines

⏺ Now I understand the plan. I need to update the success criteria sections to use the Playwright MCP for visual verifications instead of manual checks. Let me update the plan to incorporate browser automation for visual testing.

⏺ Update(thoughts/shared/plans/static-blog-migration.md)
  ⎿  Added 4 lines, removed 2 lines
      117  - [ ] Project compiles: `mix compile`
      118  - [ ] Server starts: `mix phx.server`
      119
      120 -#### Manual Verification:
      121 -- [ ] Page renders with Montserrat font visible in browser dev tools
      120 +#### Visual Verification (Playwright MCP):
      121 +- [ ] Navigate to `http://localhost:4000` using `browser_navigate`
      122 +- [ ] Take snapshot with `browser_snapshot` to verify page loads
      123 +- [ ] Use `browser_evaluate` to check font-family: `() => getComputedStyle(document.body).fontFamily` should include "Montserrat"
      124
      125  ---
      126
... (Shortened for brevity)

Now the plan was ready to be put into action.

The implementation

After reviewing the first two documents, it was time to let Claude Code start the migration.
Ideally, I should have been able to simply run /implement_plan thoughts/shared/plans/static-blog-migration.md,
and everything should have been migrated perfectly. However, knowing that the plan consisted of six different phases
and that it was not perfect, probably making coding agents encounter issues here and there,
making the context window grow in usage, I decided to make use of a simple recommendation Nacho gave us:
running each step in a different session, so each one starts with a fresh context window. So I ran:

/implement_plan Phase 1 of thoughts/shared/plans/static-blog-migration.md

This approach meant I had to do a bit more work, but that was okay. I ran the
same command for each phase and let it run while I trained, cooked, or went for a walk.
From time to time, I checked my laptop to review each phase, ask for changes if needed,
and commit the code. When the last phase was done, the blog was fully migrated, worked like a charm, and looked
just like the old one. Awesome!

Conclusion

Migrating this blog had been on my to-do list for a long time, but because of my personal situation,
I didn’t have the time or motivation to do it. The same goes for some other
personal projects I’ve put off. But using AI as a coding partner
has brought back my motivation, especially with the approach I described here,
where I guide the process to get what I want. If you’re in a similar spot—lacking time,
energy, or motivation for a side project and you want to code but aren’t excited about using AI,
I suggest giving it a try. Let it help you enjoy coding again. What small project could you bring
back with an AI teammate? Take the first step and see how AI can spark your passion for coding.

Happy (agentic) coding!

Building a simple Calendly clone with Phoenix LiveView (pt. 8)

Ricardo García Vega — Thu, 10 Feb 2022 06:29:29 +0000

In the last part of the series, we implemented the necessary logic for adding and editing event types. In this part, we will finish the even types' management screen, adding the ability to the user to clone and delete any existing event type. Let's get cracking!

The event type dropdown menu

To display the clone and delete options to the user, we will implement a dropdown menu that we will add to every even type card in the list. The final result will be something similar to the following:

Since this will not be the only dropdown that we will be using in the application, we will create a new function/stateless component to implement it, and it will consist of two parts:

An HTML element that will trigger the event to toggle the dropdown's content when the user clicks on it.
An HTML content shown/hidden to the user when the trigger gets clicked.

The function components that we have been using until now only receive data, and they always render the same HTML. How can this new component accept any HTML from outside, respecting its inner layout? Fortunately, function components have a mechanism called slots to pass them HTML blocks as in regular HTML tags. To see how it works, let's add the new component's module:

# ./lib/calendlex_web/live/admin/components/dropdown.ex

defmodule CalendlexWeb.Admin.Components.Dropdown do
  use Phoenix.Component

  alias Phoenix.LiveView.JS

  def main(assigns) do
    ~H"""
    <div
      id={@id}
      class="relative dropdown"
      phx-click-away={click_away(@id)}>
      <div
        class="flex items-baseline cursor-pointer gap-x-1 dropdown-trigger"
        phx-click={trigger_click(@id)}>
        <%= render_slot(@trigger) %>
      </div>
      <div class="absolute right-0 z-20 flex flex-col hidden py-2 mt-2 overflow-hidden text-sm text-gray-800 bg-white border shadow-md rounded-md dropdown-content">
        <%= render_slot(@inner_block) %>
      </div>
    </div>
    """
  end

  defp click_away(id), do: JS.hide(to: content_selector(id), transition: "hidden", time: 0)

  defp trigger_click(id),
    do: JS.toggle(to: content_selector(id), in: "block", out: "hidden", time: 0)

  defp content_selector(id), do: "##{id} .dropdown-content"
end

The module exposes a main/1 function which renders a regular dropdown, consisting of a parent div containing two divs:

The first one renders the trigger slot element using render_slot(@trigger).
The second one renders the nested content slot using render_slot(@inner_block).

The main difference between both slots is that @trigger is a named slot, and we can call it how we want, whereas @inner_block is a protected name representing the nested DOM elements that we will include between the Dropdown.main enclosing tags. To toggle the visibility of the dropdown, we are using the Phoenix.LiveView.JS module, which provides a series of functions to execute JavaScript utility operations on the client:

We have added a phx-click={trigger_click(@id)} to the trigger, which calls JS.toggle/1, passing the corresponding DOM selector, and the necessary classes to show/hide the dropdown's content.
The main div has a phx-click-away={click_away(@id)} event handler to hide the dropdown when the user clicks outside of it. The function uses JS.hide/1, passing the corresponding content selector and transition classes.

With the Dropdown.main component ready, let's add it to the event type card:

# ./lib/calendlex_web/live/admin/components/event_type.ex

defmodule CalendlexWeb.Admin.Components.EventType do
  use CalendlexWeb, :live_component

++alias CalendlexWeb.Admin.Components.Dropdown

  # ...
end

# ./lib/calendlex_web/live/admin/components/event_type.html.heex

<div class={"relative flex flex-col p-4 mb-2 border-gray-900 text-gray-400 bg-white cursor-pointer rounded-md shadow-sm hover:shadow-md border-t-4 #{@event_type.color}-border"}>
++<div class="absolute top-4 right-4">
++  <Dropdown.main id={"dropdown_#{@event_type.id}"}>
++    <:trigger>
++      <span class="text-gray-700"><i class="fas fa-cog"></i></span>
++    </:trigger>
++    <div class="w-48">
++      <%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.Admin.EditEventTypeLive, @event_type.id), class: "px-4 py-2 text-left hover:bg-gray-50 flex gap-x-2" do %>
++        <i class="fas fa-pencil-alt"></i> Edit
++      <% end %>
++      <a class="flex px-4 py-2 text-left hover:bg-gray-50 gap-x-2"
++                phx-target={@myself}
++                phx-click="clone_me">
++        <i class="far fa-clone"></i> Clone
++      </a>
++      <a class="flex px-4 py-2 text-left hover:bg-gray-50 gap-x-2"
++                phx-target={@myself}
++                phx-click="delete_me">
++        <i class="fas fa-trash-alt"></i> Delete
++      </a>
++    </div>
++  </Dropdown.main>
++</div>

  # ...
</div>

We invoke it using an HTML tag like any other function component, setting the id attribute it needs to toggle its content. The difference with the rest of the functions components we have implemented so far is that this one has nested content consisting of:

A <:trigger>...</:trigger> holding the content of the trigger named slot.
A set of HTML nodes corresponding to the inner_block slot, or in other words, the content that we want to toggle when the user clicks on the trigger.

If we jump back to the browser and head to http://localhost:4000/admin, we should be able of toggling the dropdown menus of the event types:

How cool is that? Regarding the dropdown options, we have an edit link pointing to the EditEventTypeLive live path we implemented in the last part and two different events for cloning and deleting the given event type, targeting the CalendlexWeb.Admin.Components.EventType live component.

Cloning an event type

Let's take care first of cloning an event type:

# ./lib/calendlex_web/live/admin/components/event_type.ex

defmodule CalendlexWeb.Admin.Components.EventType do
  use CalendlexWeb, :live_component

  alias CalendlexWeb.Admin.Components.Dropdown

  # ...

  def handle_event("clone_me", _params, socket) do
    event_type = socket.assigns.event_type

    case Calendlex.clone_event_type(event_type) do
      {:ok, new_event_type} ->
        {:noreply,
         push_redirect(socket,
           to: Routes.live_path(socket, CalendlexWeb.Admin.EditEventTypeLive, new_event_type.id)
         )}

      {:error, _} ->
        send(self(), :clone_error)
        {:noreply, socket}
    end
  end
end

The event handler takes the event_type from the socket assigns and calls Calendlex.clone_event_type/1, which we will implement in a minute. If everything goes fine, it redirects to the CalendlexWeb.Admin.EditEventTypeLive live path. On the contrary, it sends a :clone_error message to the parent live view to render the corresponding error. Let's implement the clone logic:

# ./lib/calendlex.ex

defmodule Calendlex do
  # ...

  defdelegate clone_event_type(event_type), to: Calendlex.EventType.Repo, as: :clone
end

# ./lib/calendlex/event_type/repo.ex

defmodule Calendlex.EventType.Repo do
  import Ecto.Query, only: [where: 3, order_by: 3]

  # ...

  def clone(%EventType{name: name, slug: slug} = event_type) do
    event_type
    |> Map.from_struct()
    |> Map.put(:name, "#{name} (clone)")
    |> insert()
  end
end

For the sake of simplicity, the clone/1 function takes an %EventType{}, creates a map of it, adds the (clone) string to its name, and inserts it into the database. Let's fulfill the error message in the parent live view:

# ./calendlex_web/live/admin/event_types_live.ex

defmodule CalendlexWeb.Admin.EventTypesLive do
  use CalendlexWeb, :admin_live_view

  # ...

  def handle_info(:clone_error, socket) do
    {:noreply, put_flash(socket, :error, "A similar event type already exists")}
  end
end

The message handler in the parent CalendlexWeb.Admin.EventTypesLive live view puts a flash error in the socket. Let's jump back to the browser and test everything by cloning any event type. If we clone the "15 minute meeting" event type, we should see the following in the list:

There is a new "15 minute meeting (clone)" event type. However, if we try to clone "15 minute meeting" again, we shouldn't see anything happening apart from the following error in the console due to the event type's slug unique constraint:

iex(4)> [debug] QUERY ERROR db=1.9ms queue=0.6ms idle=1604.2ms
INSERT INTO "event_types" ("color","description","duration","name","slug","inserted_at","updated_at","id") VALUES ($1,$2,$3,$4,$5,$6,$7,$8) ["blue", "Short meeting call.", 15, "15 minute meeting (clone)", "15-minute-meeting-clone", ~N[2022-02-03 06:11:52], ~N[2022-02-03 06:11:52], <<108, 252, 29, 54, 186, 121, 69, 165, 169, 33, 78, 202, 160, 116, 152, 100>>]

This is far from being the best user experience, so let's take care of displaying the flash messages properly.

Displaying flash messages to the user

Let's edit the admin.html.heex layout template and add the missing flash messages:

# ./lib/calendlex_web/templates/layout/admin.html.heex

<main role="main" class="flex flex-col flex-1">
  <div class="bg-white">
    # ...
  </div>
  <section class="container flex-1 w-3/5 py-12 mx-auto">
    <div id="flash" phx-hook="Flash">
      <%= if Map.has_key?(@flash, "info") do  %>
        <div
            class="fixed px-6 py-2 text-white uppercase bg-green-400 border border-green-500 flash alert alert-info top-10 left-1/2 rounded-md bg-opacity-80 -translate-x-1/2"
            role="alert"
            phx-click="lv:clear-flash"
            phx-value-key="info"
            >
            <%= live_flash(@flash, :info) %>
        </div>
      <% end %>

      <%= if Map.has_key?(@flash, "error") do  %>
        <div
            class="fixed px-6 py-2 text-white uppercase bg-red-400 border border-red-500 flash alert alert-error top-10 left-1/2 rounded-md bg-opacity-80 -translate-x-1/2"
            role="alert"
            phx-click="lv:clear-flash"
            phx-value-key="error"
            >
            <%= live_flash(@flash, :error) %>
        </div>
      <% end %>
    </div>

    <%= @inner_content %>
  </section>
</main>

We have added a new div with the "flash" id and to which we have attached a new hook called Flash. Inside this div, we only render the info and error flash messages if the corresponding keys exist in the @flash assigns. Both of these divs have a live event handler, phx-click="lv:clear-flash", which is a specific LiveView feature to clear flash messages when sent to the server. To finish implementing the flash messages, let's add the Flash hook to our hooks file:

// ./assets/js/hooks.js

const Hooks = {};

// ...

Hooks.Flash = {
  mounted() {
    this.initFlash();
  },
  updated() {
    this.initFlash();
  },

  initFlash() {
    const flash = this.el.querySelector('.flash');

    if (flash) {
      setTimeout(() => {
        this.pushEvent('lv:clear-flash');
      }, 2000);
    }
  },
};

// ...

The hook is straightforward. It checks if there is a flash message inside its el, sending the corresponding lv:clear-flash to the server after two seconds. Let's jump back to the browser and try to clone the "15 minute meeting" event type again and see what happens:

The error message pops up and disappears after two seconds, as expected. Moreover, we should see the corresponding info messages since we have already been adding flash messages in the previous parts. Let's go to any event type's edit page and click on the "Save" button to check that everything is working fine:

Deleting event types

The last thing that we have to implement to finish managing event types is giving the ability to the user to delete a given one. Since scheduled events require an event type, we don't want to lose track of them if we delete any. Therefore, we will implement a simple soft delete mechanism by adding an additional column to the event_types table:

❯ mix ecto.gen.migration add_deleted_at_to_event_types
* creating priv/repo/migrations/20220207062857_add_deleted_at_to_event_types.exs

# ./priv/repo/migrations/20220207062857_add_deleted_at_to_event_types.exs

defmodule Calendlex.Repo.Migrations.AddDeletedAtToEventTypes do
  use Ecto.Migration

  def change do
    alter table(:event_types) do
      add :deleted_at, :utc_datetime
    end
  end
end

Let's apply the change into the database:

❯ mix ecto.migrate

07:32:19.870 [info]  == Running 20220207062857 Calendlex.Repo.Migrations.AddDeletedAtToEventTypes.change/0 forward

07:32:19.874 [info]  alter table event_types

07:32:19.890 [info]  == Migrated 20220207062857 in 0.0s

Now we have to add the new field to the EventType schema:

# ./lib/calendlex/event_type.ex

defmodule Calendlex.EventType do
  use Ecto.Schema
  import Ecto.Changeset

  # ...

  schema "event_types" do
    # ...

    field :deleted_at, :utc_datetime

    # ...
  end

  @fields ~w(name description slug duration color deleted_at)a # We have added deleted_at to the list of fields

  # ...

With the new field ready, let's take care of the delete event handling in the event type component:

# ./lib/calendlex_web/live/admin/components/event_type.ex

defmodule CalendlexWeb.Admin.Components.EventType do
  use CalendlexWeb, :live_component

  # ...

  def handle_event("delete_me", _params, socket) do
    event_type = socket.assigns.event_type

    send(self(), {:confirm_delete, event_type})

    {:noreply, socket}
  end
end

When the component receives a delete_me event, it sends a :confirm_delete message to the main live view containing the selected event type. Since deleting an item is an operation that cannot be undone, we want to make sure that we double-check that the user wants to delete it. Therefore, we will display a confirmation message, alerting the user about the operation and asking whether we should proceed with the deletion. To achieve this, let's add use a new assign in the CalendlexWeb.Admin.EventTypesLive module:

# ./lib/calendlex_web/live/admin/event_types_live.ex

defmodule CalendlexWeb.Admin.EventTypesLive do
  use CalendlexWeb, :admin_live_view

  alias CalendlexWeb.Admin.Components.Modal

  # ...

  def handle_params(_, _, socket) do
    event_types = Calendlex.available_event_types()

    socket =
      socket
      |> assign(event_types: event_types)
      # ...
      |> assign(delete_event_type: nil)

    {:noreply, socket}
  end

  # ...

  def handle_info({:confirm_delete, event_type}, socket) do
    {:noreply, assign(socket, delete_event_type: event_type)}
  end
end

We have added a new :delete_event_type key to the socket's assigns, initialized to null. The handle_info({:confirm_delete, event_type}, socket) event handler assigns the selected event type to the socket in the :delete_event_type key, telling the LiveView that we want to delete it. To display the confirmation message to the user, we will use a modal containing the message and buttons for confirming or dismissing the action. Since we will use another confirmation message in the next episode, we are going to create a new stateless component with the modal's layout:

# ./lib/calendlex_web/live/admin/components/modal.ex

defmodule CalendlexWeb.Admin.Components.Modal do
  use Phoenix.Component

  def content(assigns) do
    ~H"""
    <div class="fixed inset-0 z-20 overflow-y-auto"
      phx-window-keydown="close_modal"
      phx-key="escape">
      <div class="flex items-end justify-center min-h-screen px-4 pt-4 pb-20 text-center sm:block sm:p-0">
        <div class="fixed inset-0 bg-white bg-opacity-75 transition-opacity" aria-hidden="true"></div>
        <span class="hidden sm:inline-block sm:align-middle sm:h-screen" aria-hidden="true">&#8203;</span>
        <div class="inline-block overflow-hidden text-left align-bottom bg-white border border-gray-200 shadow-md rounded-md transform transition-all sm:my-8 sm:align-middle sm:max-w-md sm:w-full">
          <div class="p-6 mx-auto mb-2 bg-white">
            <header class="mb-6 text-center">
              <h3 class="mb-3 text-lg font-bold text-gray-900">
                <%= render_slot(@header) %>
              </h3>
            </header>
            <%= render_slot(@inner_block) %>
            <footer class="flex mt-6 gap-x-10">
              <%= render_slot(@footer) %>
            </footer>
          </div>
        </div>
      </div>
    </div>
    """
  end

  def cancel_button(assigns) do
    ~H"""
    <button
      class="flex-1 px-4 py-2 border border-gray-800 rounded-full"
      phx-click="close_modal">
      <%= render_slot(@inner_block) %>
    </button>
    """
  end

  def confirm_button(assigns) do
    ~H"""
    <button
      class="flex-1 px-4 py-2 text-white bg-blue-600 rounded-full"
      phx-click={@event}>
      <%= render_slot(@inner_block) %>
    </button>
    """
  end
end

The modal consists of:

On top, there is a parent div representing the semitransparent overlay. It has a phx-window-keydown event binding that sends a modal_close message to the LiveView when the user presses the escape key.
Inside the overlay, it has the modal body containing the header, inner_block, and footer slots.
The module also exposes a cancel_button/1 and a confirm_button/1 buttons that render the modal buttons.

Let's add the modal to the CalendlexWeb.Admin.EventTypesLive's template:

# ./lib/calendlex_web/live/admin/event_types_live.html.heex

# ...

<%= if @delete_event_type  do %>
  <Modal.content>
    <:header>Delete <%= @delete_event_type.name %></:header>
    <p>Users will be unable to schedule further meetings with deleted event types. Meetings previously scheduled will not be affected.</p>
    <:footer>
      <Modal.cancel_button>No</Modal.cancel_button>
      <Modal.confirm_button event="delete">Yes</Modal.confirm_button>
    </:footer>
  </Modal.content>
<% end %>

It conditional adds the modal component if delete_event_type is not null. Note how we implement the corresponding slots, especially :footer, containing the Modal.confirm_button with its event assign set to delete. If we jump to the browser and try to delete an event type, we should see the following:

Nice! The only thing left is to implement both the close_modal and delete events:

# ./lib/calendlex_web/live/admin/event_types_live.ex

defmodule CalendlexWeb.Admin.EventTypesLive do
  use CalendlexWeb, :admin_live_view

  # ...

  def handle_event("modal_close", _, socket) do
    {:noreply, assign(socket, delete_event_type: nil)}
  end

  def handle_event("delete", _, socket) do
    event_type = socket.assigns.delete_event_type

    {:ok, _} = Calendlex.delete_event_type(event_type)

    socket =
      socket
      |> put_flash(:info, "Deleted")
      |> push_patch(to: Routes.live_path(socket, __MODULE__))

    {:noreply, socket}
  end
end

The close_modal handler is straightforward: it simply sets the delete_event_type socket assign back to nil, which removes the modal from the DOM on the next render. The delete handler is a bit more complex: it takes the assigned delete_event_type and calls Calendlex.delete_event_type/1, which we will implement in a minute, and redirects to the same LiveView path, which will trigger its handle_params/3 callback function, resetting its internal state. Let's add the missing functions:

# ./lib/calendlex.ex

defmodule Calendlex do
  # ...

  defdelegate delete_event_type(event_type), to: Calendlex.EventType.Repo, as: :delete
end

# ./lib/calendlex/event_type/repo.ex

defmodule Calendlex.EventType.Repo do
  # ...

  def delete(event_type) do
    event_type
    |> EventType.delete_changeset()
    |> Repo.update()
  end
end

# ./lib/calendlex/event_type.ex

defmodule Calendlex.EventType do
  use Ecto.Schema
  import Ecto.Changeset
  alias Ecto.Changeset

  # ...

  def delete_changeset(event_type) do
    event_type
    |> with_deleted_changes()
    |> validate_required(@required_fields)
  end

  # ...

  defp with_deleted_changes(%{name: name, slug: slug} = event_type) do
    event_type
    |> Changeset.change()
    |> put_change(:name, "#{name} (deleted)")
    |> put_change(:slug, "#{slug}-deleted-#{:os.system_time(:millisecond)}")
    |> put_change(:deleted_at, DateTime.truncate(DateTime.utc_now(), :second))
  end
end

The delete/1 function takes an event_type, creates the delete_changeset, and updates the event type. The delete_changeset function takes an event type, generating a new changeset with custom name, slug, and deleted_at attributes. There is still one slight change that we need to do, which is removing the deleted event types from the avalilable/0 function result, so they get removed from the UI:

# ./lib/calendlex/event_type/repo.ex

defmodule Calendlex.EventType.Repo do
  # ...

  def available do
    EventType
++  |> where([e], is_nil(e.deleted_at))
    |> order_by([e], e.name)
    |> Repo.all()
  end

  # ...
end

Let's head back to the browser and see what happens when we delete an event type:

After confirming the action, we see the corresponding success flash message, and the deleted event type is no longer in the list. And this is it for this part, and we have finally finished with all the logic behind managing event types. In the next part, we will focus on the last part of this series, which is listing and filtering scheduled events. In the meantime, you don't forget to check the final result in the live demo, or have a look at the source code.

Happy coding!

bigardone / calendlex

Simple Calendly clone with Phoenix LiveView

Live demo
Source code

Building a simple Calendly clone with Phoenix LiveView (pt. 7)

Ricardo García Vega — Mon, 24 Jan 2022 09:43:23 +0000

In the last part of the series, we started building the private admin side of our application, consisting of a new live session and layout. We also implemented the initial page for managing event types, listing all the existing ones in the database, using a new live component. Finally, we implemented our first JavaScript client hook to copy an event's public URL into the user's clipboard. In this part, we will focus on creating and editing event types. Let's get cracking!

Creating new event types

To let the user create new event types, we will add a new screen with a form to enter the new event's name, description, duration in seconds, and color. Let's add its corresponding live route to the routes file:

# ./lib/calendlex_web/router.ex

defmodule CalendlexWeb.Router do
  use CalendlexWeb, :router

  # ...

  live_session :private, on_mount: {CalendlexWeb.Live.InitAssigns, :private} do
    scope "/admin", CalendlexWeb.Admin do
      # ...

      live "/event_types/new", NewEventTypeLive
    end
  end
end

Let's continue by adding the initial live module and template:

# ./lib/calendlex_web/live/admin/new_event_type_live.ex

defmodule CalendlexWeb.Admin.NewEventTypeLive do
  use CalendlexWeb, :admin_live_view

  alias Calendlex.EventType

  def mount(_params, _session, socket) do
    event_type = %EventType{}

    socket =
      socket
      |> assign(section: "event_types")
      |> assign(page_title: "New event type")
      |> assign(event_type: event_type)
      |> assign(changeset: EventType.changeset(event_type, %{}))

    {:ok, socket}
  end
end

# ./lib/calendlex_web/live/admin/new_event_type_live.html.heex

<h1>New event type</h1>

The mount callback function assigns to the socket the layout section name, the page title, an empty event type, and its corresponding changeset that we will use to build the form's live component. Let's open the root event types template and add the related link to the button we implemented in the last part:

# ./lib/calendlex_web/live/admin/event_types_live.html.heex

<div class="flex mt-4 align-middle gap-x-6">
  <div class="flex-1"></div>
  <div class="flex-1 text-right">
--  <div class="inline-block px-4 py-1 text-blue-500 border border-blue-500 rounded-full cursor-pointer hover:bg-blue-100" do %>
++  <%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.Admin.NewEventTypeLive), class: "inline-block border border-blue-500 rounded-full px-4 py-1 text-blue-500 hover:bg-blue-100 cursor-pointer" do %>
      <i class="fas fa-plus"></i> New event type
--  </div>
++  <% end %>
  </div>
</div>

If we head to http://localhost:4000/admin in the browser and click on the button, we should see the following:

Let's edit the new template's content to include the form that we need to implement:

# ./lib/calendlex_web/live/admin/new_event_type_live.html.heex

<div class="w-4/5 p-6 mx-auto mb-2 bg-white border border-gray-200 shadow-md rounded-md">
  <.live_component
     id="new_event_type_form"
     module={CalendlexWeb.Admin.Components.EventTypeForm}
     event_type={@event_type}
     changeset={@changeset}
     />
</div>

The content of this view consists of a div containing the form's live component. Let's add the corresponding component module:

# ./lib/calendlex_web/live/admin/components/event_type_form.ex

defmodule CalendlexWeb.Admin.Components.EventTypeForm do
  use CalendlexWeb, :live_component

  alias Calendlex.EventType
  alias Phoenix.LiveComponent

  def update(
        %{
          event_type: %EventType{color: current_color, slug: slug} = event_type,
          changeset: changeset
        },
        socket
      ) do
    socket =
      socket
      |> assign(changeset: changeset)
      |> assign(event_type: event_type)
      |> assign(current_color: current_color)
      |> assign(public_url: build_public_url(socket, slug))

    {:ok, socket}
  end

  defp build_public_url(socket, nil) do
    build_public_url(socket, "")
  end

  defp build_public_url(socket, slug) do
    Routes.live_url(socket, CalendlexWeb.EventTypeLive, slug)
  end
end

The update/2 callback receives an event type and a changeset, assigning them to the socket along with current_color and public_url that we will use in a second. To build the public URL, it uses the event type's slug, along with the Routes.live_url/3 function. Let's add its template now:

# ./lib/calendlex_web/live/admin/components/event_type_form.html.heex

<div>
  <.form let={f} for={@changeset} phx-target={@myself} phx-change="change" phx-submit="submit">
  <header class="flex items-center px-6 pb-6 mb-6 -mx-6 text-right border-b border-gray-300 gap-x-4">
    <h3 class="text-gray-900">What event is this?</h3>
  </header>
  <div class="w-3/5 mb-6">
    <%= label f, :name, class: "block mb-2 text-sm" %>
    <%= text_input f, :name, class: "w-full p-2 border rounded-md", autofocus: "", required: "" %>
    <div class="mt-2 text-sm text-blue-500">
      <span class="text-gray-500">Public url:</span>
      <%= @public_url %>
    </div>
    <%= error_tag f, :name %>
  </div>
  <div class="w-3/5 mb-6">
    <%= label f, :description, class: "block mb-2 text-sm" %>
    <%= textarea f, :description, class: "w-full p-2 border h-36 rounded-md" %>
    <%= error_tag f, :description %>
  </div>
  <div class="w-3/5 mb-6">
    <%= label f, :duration, class: "block mb-2 text-sm" %>
    <div class="flex items-center gap-x-2">
      <%= text_input f, :duration, class: "w-20 p-2 border rounded-md", required: "", type: "number", min: 1 %>
      minutes
    </div>
    <%= error_tag f, :duration %>
  </div>
  <div class="w-3/5 mb-6">
    <%= label f, :color, class: "block mb-2 text-sm" %>
    <div class="flex gap-x-2">
      <%= for color <- ~w(gray red yellow green blue indigo pink purple) do %>
        <label class="relative cursor-pointer" phx-target={@myself} phx-click="set_color" phx-value-color={color}>
          <div class={"inline-block w-8 h-8 #{color}-bg rounded-full"}></div>
          <%= radio_button f, :color, color, class: "hidden" %>
          <%= if @current_color == color do %>
            <span class="absolute z-10 inline-block w-4 h-4 text-white top-1 left-1/2 -translate-x-1/2">
              <i class="fas fa-check"></i>
            </span>
          <% end %>
        </label>
      <% end %>
    </div>
    <%= error_tag f, :color %>
  </div>
  <footer class="flex items-center justify-end px-6 pt-6 -mx-6 text-right border-t border-gray-300 gap-x-4">
    <%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.Admin.EventTypesLive) do %>Cancel<% end %>
    <button class="px-4 py-2 text-white bg-blue-600 rounded-full" type="submit" phx-disable-with="Saving...">Save</button>
  </footer>
  </.form>
</div>

The template consists of a Phoenix form for the component's changeset assigned in the update/2 callback we just implemented. We are adding a phx-target={@myself} attribute, which makes the submit and change events target the component instance rather than the parent live view. Therefore, we can group all the form's internal logic in a single place instead of duplicating it in the creating and editing event types views. The rest of the form's implementation is pretty straightforward, except for two things:

We will display the public URL of the event type while the user types its name.
The color selector consists of hidden radio buttons with a visible color circle and a check icon for the selected value.

If we jump back to the browser, we should see the following:

Auto-generating the event type's slug

To generate the event type's URL slug, we will auto-generate it taking advantage of Ecto's changesets instead of relying on the user to type a proper one. The idea is to build a valid URL path value from the event type's name, and for this, we can use Slugify. Let's add it to the project's dependencies and install it:

# ./mix.exs

defmodule Calendlex.MixProject do
  use Mix.Project

  # ...

  defp deps do
    [
      # ...
      {:slugify, "~> 1.3"}
    ]
  end

  # ...
end

Let's edit the EventType schema module to include the slug in its changeset:

# ./lib/calendlex/event_type.ex

defmodule Calendlex.EventType do
  use Ecto.Schema
  import Ecto.Changeset

  # ...

  def changeset(event_type \\ %EventType{}, attrs) do
    event_type
    |> cast(attrs, @fields)
    |> build_slug() # We are adding this
    |> validate_required(@required_fields)
    |> unique_constraint(:slug, name: "event_types_slug_index")
  end

  defp build_slug(%{changes: %{name: name}} = changeset) do
    put_change(changeset, :slug, Slug.slugify(name))
  end

  defp build_slug(changeset), do: changeset
end

After casting the attributes, we add a build_slug/1 private function to the changeset/2 pipeline. This function checks whether name has changed, generating the slug with its new value and adding it to the changeset. Let's jump to IEX and try it out:

Interactive Elixir (1.13.1) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> attrs = %{name: "My event type", description: "Fake event type", duration: 30, color: "blue"}
%{
  color: "blue",
  description: "Fake event type",
  duration: 30,
  name: "My event type"
}
iex(2)> Calendlex.EventType.changeset(attrs)
#Ecto.Changeset<
  action: nil,
  changes: %{
    color: "blue",
    description: "Fake event type",
    duration: 30,
    name: "My event type",
    slug: "my-event-type"
  },
  errors: [],
  data: #Calendlex.EventType<>,
  valid?: true
>
iex(3)>

We can see that the changeset has a slug key in its changes map, with a value of my-event-type, generated from name. Cool! Now we can go back to the component's module and implement the change event handler:

# ./lib/calendlex_web/live/admin/components/event_type_form.ex

defmodule CalendlexWeb.Admin.Components.EventTypeForm do
  use CalendlexWeb, :live_component

  alias Ecto.Changeset
  # ...

  def handle_event(
        "change",
        %{"event_type" => params},
        %{assigns: %{event_type: event_type}} = socket
      ) do
    changeset = EventType.changeset(event_type, params)
    public_url = build_public_url(socket, get_slug(changeset))

    {:noreply, assign(socket, changeset: changeset, public_url: public_url)}
  end

  # ...

  defp get_slug(%Changeset{changes: %{slug: slug}}), do: slug
  defp get_slug(%Changeset{data: %{slug: slug}}), do: slug
end

The handler takes the form values in event_type and the assigned event type to generate a new changeset. From this changeset, it takes the slug value and generates the corresponding public_url, assigning both to the socket. Let's head back to the browser and start typing the name's value:

While we type, we can see that the public URL auto-updates, yay!

Setting the current color

Let's take a closer look at the color selector:

# ./lib/calendlex_web/live/admin/components/event_type_form.html.heex

# ...

    <div class="flex gap-x-2">
      <%= for color <- ~w(gray red yellow green blue indigo pink purple) do %>
        <label class="relative cursor-pointer" phx-target={@myself} phx-click="set_color" phx-value-color={color}>
          <div class={"inline-block w-8 h-8 #{color}-bg rounded-full"}></div>
          <%= radio_button f, :color, color, class: "hidden" %>
          <%= if @current_color == color do %>
            <span class="absolute z-10 inline-block w-4 h-4 text-white top-1 left-1/2 -translate-x-1/2">
              <i class="fas fa-check"></i>
            </span>
          <% end %>
        </label>
      <% end %>
    </div>

# ...

The selector consists of radio buttons corresponding to a color in the list, hidden using CSS. The labels have a phx-click event that triggers a set_color event with the corresponding color. If any color matches current_color assigned in the socket, we add a check icon to mark it. Let's implement the event handler in the view's module:

# ./lib/calendlex_web/live/admin/components/event_type_form.ex

defmodule CalendlexWeb.Admin.Components.EventTypeForm do
  use CalendlexWeb, :live_component

  # ...

  def handle_event("set_color", %{"color" => color}, %{assigns: %{changeset: changeset}} = socket) do
    changeset = Ecto.Changeset.put_change(changeset, :color, color)

    {:noreply, assign(socket, changeset: changeset, current_color: color)}
  end

  # ...
end

The callback function takes color from the incoming parameters, adds it to the changeset, and assigns it to the socket as current_color. If we now head back to the browser and select a color, we should see the check icon correctly.

Inserting the event type into the database

With the form's logic fully implemented, we can insert the new event type into the database We've implemented all the form's internal logic in the live component module. However, inserting and updating an event type will have different implementations. Therefore, it makes sense delegating the proper persisting logic the parent to the live view module that renders the form. Since the form has the target={@myself} attribute, any event is handled by the component's module, and to send the event back to the CalendlexWeb.Admin.NewEventTypeLive module, we have to do the following:

# ./lib/calendlex_web/live/admin/components/event_type_form.ex

defmodule CalendlexWeb.Admin.Components.EventTypeForm do
  use CalendlexWeb, :live_component

  # ...

  def handle_event("submit", %{"event_type" => params}, socket) do
    send(self(), {:submit, params})

    {:noreply, socket}
  end

  # ...
end

The parent LiveView and the form component run in the same process. Therefore, sending a message from the component to the parent view is as simple as using Kernel.send/2, using self() to get the corresponding PID. Let's add the necessary event handler to the CalendlexWeb.Admin.NewEventTypeLive module:

# ./lib/calendlex_web/live/admin/new_event_type_live.ex

defmodule CalendlexWeb.Admin.NewEventTypeLive do
  use CalendlexWeb, :admin_live_view

  # ...

  def handle_info({:submit, params}, socket) do
    params
    |> Calendlex.insert_event_type()
    |> case do
      {:ok, event_type} ->
        socket = put_flash(socket, :info, "Saved")

        {:noreply,
         push_redirect(socket,
           to: Routes.live_path(socket, CalendlexWeb.Admin.EditEventTypeLive, event_type.id)
         )}

      {:error, changeset} ->
        {:noreply, assign(socket, changeset: changeset)}
    end
  end
end

Taking params from the message, it calls Calendlex.insert_event_type(), that we will implement in a minute, it redirects to the editing page of the created event type. On any error, it assigns the changeset to the socket. Let's add the proxy function to the Calendlex module and its implementation in the corresponding module:

# ./lib/calendlex.ex

defmodule Calendlex do
  # ...

  defdelegate insert_event_type(params), to: Calendlex.EventType.Repo, as: :insert
end

# ./lib/calendlex/event_type/repo.ex

defmodule Calendlex.EventType.Repo do
  # ...

  def insert(params) do
    params
    |> EventType.changeset()
    |> Repo.insert()
  end
end

To fix the last error, we must add the edit event type route and implement its corresponding LiveView module and template. The good news is that it will be pretty similar to the new live view we just implemented, and we have already taken care of the form's logic that we will reuse. Let's do this!

Editing event types

Let's start by adding the new route to the router file:

# ./lib/calendlex_web/router.ex

defmodule CalendlexWeb.Router do
  use CalendlexWeb, :router

  # ...


  live_session :private, on_mount: {CalendlexWeb.Live.InitAssigns, :private} do
    scope "/admin", CalendlexWeb.Admin do
      # ...

      live_session :private, on_mount: {CalendlexWeb.Live.InitAssigns, :private} do
    scope "/admin", CalendlexWeb.Admin do
    end
  end

  # ...
end

To continue, let's implement the live view module:

# ./lib/calendlex_web/live/admin/edit_event_type_live.ex

defmodule CalendlexWeb.Admin.EditEventTypeLive do
  use CalendlexWeb, :admin_live_view

  alias Calendlex.EventType

  def mount(%{"id" => id}, _session, socket) do
    case Calendlex.get_event_type_by_id(id) do
      {:ok, %EventType{name: name} = event_type} ->
        socket =
          socket
          |> assign(section: "event_types")
          |> assign(page_title: name)
          |> assign(event_type: event_type)
          |> assign(changeset: EventType.changeset(event_type, %{}))

        {:ok, socket}

      _ ->
        {:ok, socket, layout: {CalendlexWeb.LayoutView, "not_found.html"}}
    end
  end

  def handle_info({:submit, params}, %{assigns: %{event_type: event_type}} = socket) do
    event_type
    |> Calendlex.update_event_type(params)
    |> case do
      {:ok, event_type} ->
        socket =
          socket
          |> put_flash(:info, "Saved")
          |> assign(event_type: event_type)
          |> assign(changeset: EventType.changeset(event_type, %{}))

        {:noreply, socket}

      {:error, changeset} ->
        {:noreply, assign(socket, changeset: changeset)}
    end
  end
end

The EditEventTypeLive module is very similar to NewEventTypeLive, except that:

In the mount callback function, instead of using an empty EventType, it takes an id from the parameters, gets the event type from the database, building the changeset from it. If the event type is not found, it renders the not_found page.
While handling the :submit message from the form component, it calls Calendlex.update_event_type/1, which we need to implement, reassigning the changed event type and changeset to the socket on success.

Let's implement the necessary functions to find and update an existing event type:

# ./lib/calendlex.ex

defmodule Calendlex do
  # ...

  defdelegate get_event_type_by_id(id), to: Calendlex.EventType.Repo, as: :get

  defdelegate update_event_type(params), to: Calendlex.EventType.Repo, as: :update
end

# ./lib/calendlex/event_type/repo.ex

defmodule Calendlex.EventType.Repo do
  # ...

  def get(id) do
    case Repo.get(EventType, id) do
      nil ->
        {:error, :not_found}

      event_type ->
        {:ok, event_type}
    end
  end

  def update(event_type, params) do
    event_type
    |> EventType.changeset(params)
    |> Repo.update()
  end
end

The only thing left is adding the edit event type template:

# ./lib/calendlex_web/live/admin/edit_event_type_live.html.heex

<div class="w-4/5 mx-auto mb-6 text-right">
  <%= link to: Routes.live_path(@socket, CalendlexWeb.EventTypeLive, @event_type.slug), target: "_blank", class: "text-blue-500" do %>
    <i class="fas fa-external-link-alt"></i> view live page
  <% end %>
</div>
<div class="w-4/5 p-6 mx-auto mb-2 bg-white border border-gray-200 shadow-md rounded-md">
  <.live_component
     id="edit_event_type_form"
     module={CalendlexWeb.Admin.Components.EventTypeForm}
     event_type={@event_type}
     changeset={@changeset}
     />
</div>

Let's head to http://localhost:4000/admin/event_types/new in the browser and create a new event type to see what happens:

When we submit the form, it creates the new event type, and we get redirected to the edit live view, where apart from the form, there is a link to the event type's public URL. To finish this part, let's make it possible to edit an event type from the main list:

# ./lib/calendlex_web/live/admin/components/event_type.html.heex

<div class={"relative flex flex-col p-4 mb-2 border-gray-900 text-gray-400 bg-white cursor-pointer rounded-md shadow-sm hover:shadow-md border-t-4 #{@event_type.color}-border"}>
++<%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.Admin.EditEventTypeLive, @event_type.id) do %>
    <header class="mb-4">
      <h3 class="mb-1 text-xl text-gray-800"><%= @event_type.name %></h3>
      <div class="mb-2 text-sm"><%= @event_type.duration %> mins</div>
      <div><%= @event_type.description %></div>
    </header>
    <div class="flex-1">
      <%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.EventTypeLive, @event_type.slug), class: "text-blue-500 hover:underline" do %>View booking page<% end %>
    </div>
++<% end %>
  <footer class="flex items-center h-16 px-4 mt-4 -m-4 text-sm border-t border-gray-200">
    <button
        id={"clipboard_#{@event_type.id}"}
        class="text-blue-500"
        data-content={Routes.live_url(@socket, CalendlexWeb.EventTypeLive, @event_type.slug)}
        phx-hook="Clipboard">
      <i class="far fa-clone"></i> Copy link
    </button>
  </footer>
</div>

And that's it for this part. In the following part, we will finish the event type's management section by adding the last touches, including showing a flash message to the user when an event type gets saved. We will also add a dropdown to the card component to let the user clone and delete the corresponding event type. In the meantime, you don't forget to check the final result in the live demo, or have a look at the source code.

Happy coding!

bigardone / calendlex

Simple Calendly clone with Phoenix LiveView

Building a simple Calendly clone with Phoenix LiveView (pt. 6)

Ricardo García Vega — Wed, 19 Jan 2022 05:18:52 +0000

In the last part of the series, we generated the available time slots for a given data and rendered them as clickable items in the calendar's live view. We also implemented the booking form, which schedules a new event for the selected event type, date, and time slot. In this part, we are going to start implementing the private side of our application, in which we will be able to manage the existing event types and create new ones. Let's get cracking!

The private admin scope

Since this section of the application will expose sensitive data, we don't want to make it accessible to anyone not authorized. Therefore, we must use an authentication mechanism to protect all the admin routes. In this particular case, we will use basic HTTP authentication for the sake of simplicity. But how can we protect a bunch of live routes using this approach? Let's jump to the router file and find out:

# ./lib/calendlex_web/router.ex

defmodule CalendlexWeb.Router do
  use CalendlexWeb, :router

  import Plug.BasicAuth

  # ...

  pipeline :auth do
    plug :basic_auth, Application.compile_env(:calendlex, :basic_auth)
  end

  live_session :private, on_mount: {CalendlexWeb.Live.InitAssigns, :private} do
    scope "/admin", CalendlexWeb.Admin do
      pipe_through :browser
      pipe_through :auth

      live "/", EventTypesLive
    end
  end

  # ...

end

We are importing Plug's BasicAuth plug, which will cover all the HTTP authentication. Next, we create a new pipeline, :auth, which contains the :basic_auth plug and its configuration, which we take from the application. Finally, we create a new :private live session holding the /admin scope, which pipes through :auth and contains the private live routes. Our project is not compiling anymore, so let's fix the errors. First of all, let's add the corresponding authentication configuration:

# ./config/config.exs

import Config

config :calendlex,
  # ...
  basic_auth: [username: "admin", password: "admin"]

The configuration is straightforward, setting admin as the username and password. Now let's implement the new :private live session in the InitAssigns module:

# ./lib/calendlex_web/live/init_assigns.ex

defmodule CalendlexWeb.Live.InitAssigns do
  import Phoenix.LiveView

  # ...

  def on_mount(:private, _params, _session, socket) do
    owner = Application.get_env(:calendlex, :owner)

    {:cont, assign(socket, :owner, owner)}
  end
end

The on_mount/4 function takes the owner from the configuration and assigns it to the socket, making it accessible within all the /admin/* routes. Now we are ready to implement the new admin EventTypesLive live view, let's go ahead and create the initial module and template:

# ../lib/calendlex_web/live/admin/event_types_live.ex

defmodule CalendlexWeb.Admin.EventTypesLive do
  use CalendlexWeb, :live_view

  @impl LiveView
  def mount(_params, _session, socket) do
    {:ok, socket, temporary_assigns: [event_types: []]}
  end
end

# ../lib/calendlex_web/live/admin/event_types_live.html.heex

<h1>Event types</h1>

Our project should compile again, and if we visit http://localhost:4000/admin in the browser, we should see the Basic HTTP authentication plug in action:

Entering admin/admin should let us see the initial template we just created a minute ago:

The admin layout

Before continuing any further, let's stop for a second and think about what we will build in this and the following parts. We will be focusing on the private admin side of the application, which will have its navigation menu only visible for authenticated users. Since we are already using the current existing application layout, located in lib/calendlex_web/templates/layout/app.html.heex, for the public part, it makes sense to create a totally different new layout for all the new admin screens, right? Let's go ahead and add the corresponding template file:

# ./lib/calendlex_web/templates/layout/admin.html.heex

<main role="main" class="flex flex-col flex-1">
  <div class="bg-white">
    <header class="container w-3/5 pt-12 mx-auto">
      <h1 class="mb-3 text-2xl font-medium text-gray-900">My Calendlex</h1>
      <nav class="flex gap-x-6">
        <%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.Admin.EventTypesLive), class: admin_nav_link_classes(@section == "event_types") do %>
          Event types
        <% end %>
      </nav>
    </header>
  </div>
  <section class="container flex-1 w-3/5 py-12 mx-auto">
    <%= @inner_content %>
  </section>
</main>

The template consists of the main navigation menu shared by all the admin pages and the inner content corresponding to the current one. To style the active navigation item, we use the admin_nav_link_classes/1 function that we have to add to the CalendlexWeb.LayoutView module:

# ./lib/calendlex_web/views/layout_view.ex

defmodule CalendlexWeb.LayoutView do
  use CalendlexWeb, :view

  alias CalendlexWeb.LiveViewHelpers

  # ...

  def admin_nav_link_classes(is_current) do
    LiveViewHelpers.class_list([
      {"py-6 font-medium text-gray-400 border-b-2 border-white hover:border-gray-400 hover:text-gray-600",
       true},
      {"text-gray-600 border-blue-500 hover:text-gray-600 hover:border-blue-500", is_current}
    ])
  end
end

To apply the new admin layout to all the admin pages, let's add a new macro to the CalendlexWeb module:

# ./lib/calendlex_web.ex

defmodule CalendlexWeb do
  # ...

  def admin_live_view do
    quote do
      use Phoenix.LiveView,
        layout: {CalendlexWeb.LayoutView, "admin.html"}

      import CalendlexWeb.LiveViewHelpers

      alias Phoenix.LiveView

      unquote(view_helpers())
    end
  end

  # ...
end

Now we can update the initial CalendlexWeb.Admin.EventTypesLive to make use of the new admin macro and assign to the socket all the necessary data that we need:

# ./lib/calendlex_web/live/admin/event_types_live.ex

defmodule CalendlexWeb.Admin.EventTypesLive do
  # using the new macro with the admin layout
  use CalendlexWeb, :admin_live_view

  @impl LiveView
  def mount(_params, _session, socket) do
    {:ok, socket, temporary_assigns: [event_types: []]}
  end

  @impl LiveView
  def handle_params(_, _, socket) do
    socket =
      socket
      |> assign(section: "event_types")
      |> assign(page_title: "Event types")

    {:noreply, socket}
  end
end

If we now jump back to the browser, we should see the following:

Much better, moving on!

Listing event types

With the admin layout ready, let's list all the available event types:

# ./lib/calendlex_web/live/admin/event_types_live.ex

defmodule CalendlexWeb.Admin.EventTypesLive do
  # ...

  @impl LiveView
  def handle_params(_, _, socket) do
    event_types = Calendlex.available_event_types()

    socket =
      socket
      |> assign(section: "event_types")
      |> assign(page_title: "Event types")
      |> assign(event_types: event_types)
      |> assign(event_types_count: length(event_types))

    {:noreply, socket}
  end
end

Using the same Calendlex.available_event_types() function we created in a previous part of the series, we get all the available event types from the database and assign them to the socket. We also assign the length of the list in the event_types_count key. But why don't we use the lenght/1 directly in the template instead of assigning it to the socket? There is a reason related to LiveView's temporary assigns, but we will get to it later once we implement deleting event types. Now let's edit the template to render the event types assigned to the socket:

# ../lib/calendlex_web/live/admin/event_types_live.html.heex

<div class="flex mt-4 align-middle gap-x-6">
  <div class="flex-1"></div>
  <div class="flex-1 text-right">
    <div class="inline-block px-4 py-1 text-blue-500 border border-blue-500 rounded-full cursor-pointer hover:bg-blue-100" do %>
      <i class="fas fa-plus"></i> New event type
    </div>
  </div>
</div>
<%= if @event_types_count > 0 do %>
  <div class="mt-4 grid grid-cols-3 gap-6">
    <%= for event_type <- @event_types do %>
      <.live_component module={CalendlexWeb.Admin.Components.EventType} id={"event_type_" <> event_type.id} event_type={event_type} />
    <% end %>
  </div>
<% else %>
  <div class="mt-4">
    <h3 class="mb-2 text-xl">You don't have any event types yet.</h3>
    <p class="">You'll want to add an event type to allow people to schedule with you.</p>
  </div>
<% end %>

In the template, we display a fake button to add new event types that we will implement later in the series. Depending on the event types, we render them using a new live component or display an info message when no items are available.

The event type live component

Live components, also known as stateful components, are the other component type within LiveView. It is a way of grouping state, markup, and events, and they even have a different life-cycle. Since we will implement multiple actions on each event type, like deleting and cloning, it makes sense to have all this related functionality in the component rather than in the main live view. Let's go ahead and write the initial implementation of the component:

# ./lib/calendlex_web/live/admin/components/event_type.ex

defmodule CalendlexWeb.Admin.Components.EventType do
  use CalendlexWeb, :live_component

  def mount(socket) do
    {:ok, socket}
  end
end

A live component's life-cycle looks like the following:

mount(socket) -> update(assigns, socket) -> render(assigns)

mount/1 is called once when the component is added to the page. update/2 is invoked immediately after mount/1 and every update from the live view. render/1 works the same as in a regular live view. If update/2 does not exist, mount/1 merges all the assigns automatically into the socket. In our case, since we are passing the event type in the event_type assign, we can use it in its render template:

# ./lib/calendlex_web/live/admin/components/event_type.html.heex

<div class={"relative flex flex-col p-4 mb-2 border-gray-900 text-gray-400 bg-white cursor-pointer rounded-md shadow-sm hover:shadow-md border-t-4 #{@event_type.color}-border"}>
  <header class="mb-4">
    <h3 class="mb-1 text-xl text-gray-800"><%= @event_type.name %></h3>
    <div class="mb-2 text-sm"><%= @event_type.duration %> mins</div>
    <div><%= @event_type.description %></div>
  </header>
  <div class="flex-1">
    <%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.EventTypeLive, @event_type.slug), class: "text-blue-500 hover:underline" do %>View booking page<% end %>
  </div>
  <footer class="flex items-center h-16 px-4 mt-4 -m-4 text-sm border-t border-gray-200">
    <button class="text-blue-500">
      <i class="far fa-clone"></i> Copy link
    </button>
  </footer>
</div>

The template's content is pretty straightforward, displaying the event type's name, duration, and description. We are also adding a link to the public scheduling page we implemented in the previous parts of the series. Finally, we are also adding a convenient copy link, which will copy the public link to the user's clipboard on click. Jumping back to the browser, we should see something like the following:

Looking great so far! However, how can we implement the clipboard functionality?

LiveView's JavaScript client hooks

LiveView makes interoperability between its rendered HTML and external JavaScript very easy, thanks to client hooks, which are nothing but a JS object with predefined life-cycle callbacks like mounted, beforeUpdate, updated, etc. You can attach a hook to any node by adding the phx-hook attribute. Let's see them in action by creating a hook to copy the event type's link to the clipboard:

// ./assets/js/hooks.js

const Hooks = {};

Hooks.Clipboard = {
  mounted() {
    const originalInnerHTML = this.el.innerHTML;
    const { content } = this.el.dataset;

    this.el.addEventListener('click', () => {
      navigator.clipboard.writeText(content);

      this.el.innerHTML = '<i class="fas fa-check"></i> Copied';

      setTimeout(() => {
        this.el.innerHTML = originalInnerHTML;
      }, 2000);
    });
  },
};

export default Hooks;

We have created a ./assets/js/hooks.js file, that exposes a Hooks object with the Clipboard hooks. Clipboard implements the mounted callback which stores in a variable the current inner HTML from the this.el, in our case it will correspond to the copy-link button (the node with the phx-hook="Clipboard" attribute). It also takes the content to copy from el's dataset, adds a click event listener to the button that writes content to the browser's clipboard, and changes the inner HTML to a success message. Finally, it restores the button's inner HTML with its original content after two seconds. Now we need to add the exported hooks to the live socket connection:

// ./assets/js/app.js

//...

import Hooks from './hooks';

//...

const liveSocket = new LiveSocket('/live', Socket, {
  hooks: Hooks,
  //...
});

To connect the hook to the button in the event type live component, let's edit its template and add both the data-content and phx-hook attributes:

# ./lib/calendlex_web/live/admin/components/event_type.html.heex

<div class={"relative flex flex-col p-4 mb-2 border-gray-900 text-gray-400 bg-white cursor-pointer rounded-md shadow-sm hover:shadow-md border-t-4 #{@event_type.color}-border"}>
  <header class="mb-4">
    <h3 class="mb-1 text-xl text-gray-800"><%= @event_type.name %></h3>
    <div class="mb-2 text-sm"><%= @event_type.duration %> mins</div>
    <div><%= @event_type.description %></div>
  </header>
  <div class="flex-1">
    <%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.EventTypeLive, @event_type.slug), class: "text-blue-500 hover:underline" do %>View booking page<% end %>
  </div>
  <footer class="flex items-center h-16 px-4 mt-4 -m-4 text-sm border-t border-gray-200">
    <button
+       id={"clipboard_#{@event_type.id}"}
        class="text-blue-500"
+       data-content={Routes.live_url(@socket, CalendlexWeb.EventTypeLive, @event_type.slug)}
+       phx-hook="Clipboard">
      <i class="far fa-clone"></i> Copy link
    </button>
  </footer>
</div>

We are also adding the id attribute since hooks require a unique DOM ID to work correctly. Let's jump back to the browser and see what happens when we now click on the button:

It works like a charm, yay! In the next part, we will continue with event types management, implementing the corresponding live views to edit existing even types and create new ones, using more live components and hooks. In the meantime, you can check the final result in the live demo, or have a look at the source code.

Happy coding!

bigardone / calendlex

Simple Calendly clone with Phoenix LiveView

Building a simple Calendly clone with Phoenix LiveView (pt. 5)

Ricardo García Vega — Thu, 09 Dec 2021 06:56:43 +0000

In the last part of the series, we implemented the monthly calendar, making it possible to navigate through months taking advantage of LiveView's live patch. We also added the ability to select a date, updating the current one assigned in the live view. In this part, we will use the date chosen by the user to calculate all the available time slots in the day and render them back, letting the user select one. Finally, we will implement a new live view to render the form for booking the time slot chosen, eventually creating a newly scheduled event once submitted. Let's get cracking!

Generating the available time slots

To generate the available time slots on a given date, let's edit the EventTypeLive module:

# ./lib/calendlex_web/live/event_type_live.ex

defmodule CalendlexWeb.EventTypeLive do
  use CalendlexWeb, :live_view

  # ...

  def mount(%{"event_type_slug" => slug}, _session, socket) do
    case Calendlex.get_event_type_by_slug(slug) do
      {:ok, event_type} ->
        # ...

        {:ok, socket, temporary_assigns: [time_slots: []]}

      {:error, :not_found} ->
        {:ok, socket, layout: {CalendlexWeb.LayoutView, "not_found.html"}}
    end
  end

  # ...

  def handle_params(params, _uri, socket) do
    socket =
      socket
      |> assign_dates(params)
      |> assign_time_slots(params) # added this

    {:noreply, socket}
  end

  # ...

  defp assign_time_slots(socket, %{"date" => _}) do
    date = socket.assigns.current
    time_zone = socket.assigns.owner.time_zone
    event_duration = socket.assigns.event_type.duration

    time_slots = Calendlex.build_time_slots(date, time_zone, event_duration)

    socket
    |> assign(time_slots: time_slots)
    |> assign(selected_date: date)
  end

  defp assign_time_slots(socket, _), do: socket
end

First, we assign temporary time_slots as an empty list. Next, we add a new private function called assign_time_slots/2 that takes the socket and params. Using date, time_zone, and event.duration from the socket assigns, it calls a new Calendlex.build_time_slots/3 function to build the time slots, and finally assigns them along the current_date to the socket. Let's add build_time_slots/3 to the Calendlex module:

# ./lib/calendlex.ex

defmodule Calendlex do
  # ...

  defdelegate build_time_slots(date, time_zone, duration), to: Calendlex.TimeSlots, as: :build
end

Following the same pattern we've been using so far, it delegates the call to a new Calendlex.TimeSlots.build/3 function. Let's implement this module:

# ./lib/calendlex/time_slots.ex

defmodule Calendlex.TimeSlots do
  @spec build(Date.t(), String.t(), non_neg_integer) :: [DateTime.t()]
  def build(date, time_zone, duration) do
    from =
      date
      |> Timex.to_datetime(time_zone)
      |> Timex.set(hour: day_start())

    to = Timex.set(from, hour: day_end())

    from
    |> Stream.iterate(&DateTime.add(&1, duration * 60, :second))
    |> Stream.take_while(&(DateTime.diff(to, &1) > 0))
    |> Enum.to_list()
  end

  defp day_start, do: Application.get_env(:calendlex, :owner)[:day_start]

  defp day_end, do: Application.get_env(:calendlex, :owner)[:day_end]
end

This function does the following:

It calculates the owner's start-of-the-day time using the date, the visitor's time zone, and the owner's configuration, binding it to the from variable.
Using the owner's configuration, it calculates the end-of-the-day time, binding it to to.
Iterating over a stream of values starting from from in steps of duration in minutes, it takes items until to is reached.
Finally, it returns the stream converted into a list.

We haven't added the corresponding owner's configuration values yet, so let's go ahead and do it now:

# ./config/config.exs

config :calendlex,
  # ...
  owner: %{
    name: "Bigardone",
    time_zone: "Europe/Madrid",
    day_start: 9,
    day_end: 19
  }

  # ...

If we restart Phoenix's server, everything should compile again. Now we can render the time slots, so let's edit the CalendlexWeb.EventTypeLive template file:

# ./lib/calendlex_web/live/event_type_live.html.heex

<div class="w-3/5 mx-auto">
  <div class="flex flex-auto p-6 mb-2 bg-white border border-gray-200 shadow-md rounded-md gap-x-2">

  # ...

    <%= if @time_slots !== [] do %>
      <div class="pl-8 overflow-y-auto border-l border-gray-100 w-80 h-96">
        <header class="mb-8">
          <h3 class="text-lg font-semibold text-gray-900">
            <%= Timex.format!(@selected_date, "{WDfull}, {Mshort} {D}") %>
          </h3>
        </header>
        <div class="flex-1 overflow-y-auto">
          <%= for time_slot <- @time_slots do %>
            <EventType.time_slot
              id={"time_slot_#{time_slot}"}
              socket={@socket}
              time_slot={time_slot}
              time_zone={@time_zone}
              event_type={@event_type} />
          <% end %>
        </div>
      </div>
    <% end %>
  </div>
</div>

We render the corresponding HTML section block if the assigned time_slots is not an empty list. For each time slot, we are going to use another function component so let's implement it:

# ./lib/calendlex_web/live/components/event_type.ex

defmodule CalendlexWeb.Components.EventType do
  use Phoenix.Component

  # ...
  alias CalendlexWeb.Router.Helpers, as: Routes

  # ...

  def time_slot(
        %{
          socket: socket,
          event_type: event_type,
          time_slot: time_slot,
          time_zone: time_zone
        } = assigns
      ) do
    text =
      time_slot
      |> DateTime.shift_zone!(time_zone)
      |> Timex.format!("{h24}:{m}")

    slot_string = DateTime.to_iso8601(time_slot)

    schedule_path =
      socket
      |> Routes.live_path(CalendlexWeb.ScheduleEventLive, event_type.slug, slot_string)
      |> URI.decode()

    assigns =
      assigns
      |> assign(text: text)
      |> assign(schedule_path: schedule_path)

    ~H"""
    <%= live_redirect to: @schedule_path, class: "text-center block w-full p-4 mb-2 font-bold text-blue-600 border border-blue-300 rounded-md hover:border-blue-600" do %>
      <%= @text %>
    <% end %>
    """
  end
end

Taking time_slot, we build text and slot_string. We will use the first as the time slot's button text and the second to build the path to the booking form page. This new live view does not exist yet, thus the compilation error that you can see in your terminal/browser:

[error] #PID<0.636.0> running CalendlexWeb.Endpoint (connection #PID<0.635.0>, stream id 1) terminated
Server: localhost:4000 (http)
Request: GET /15-minute-meeting?date=2021-12-20
** (exit) an exception was raised:
    ** (ArgumentError) no action CalendlexWeb.ScheduleEventLive for CalendlexWeb.Router.Helpers.live_path/4. The following actions/clauses are supported:

    live_path(conn_or_endpoint, CalendlexWeb.EventTypeLive, event_type_slug, params \\ [])
    live_path(conn_or_endpoint, CalendlexWeb.PageLive, params \\ [])
        (phoenix 1.6.2) lib/phoenix/router/helpers.ex:387: Phoenix.Router.Helpers.invalid_route_error/3
        (calendlex 0.1.0) lib/calendlex_web/live/components/event_type.ex:123: CalendlexWeb.Components.EventType.time_slot/1
        (phoenix_live_view 0.17.5) lib/phoenix_live_view/helpers.ex:578: Phoenix.LiveView.Helpers.component/2
        (calendlex 0.1.0) lib/calendlex_web/live/event_type_live.html.heex:43: anonymous fn/4 in CalendlexWeb.EventTypeLive.render/1
        (elixir 1.12.3) lib/enum.ex:2385: Enum."-reduce/3-lists^foldl/2-0-"/3
        ...

To fix the error, let's add the corresponding route, empty LiveView module, and template:

# ./lib/calendlex_web/router.ex

defmodule CalendlexWeb.Router do
  use CalendlexWeb, :router

  # ...

  live_session :public, on_mount: CalendlexWeb.Live.InitAssigns do
    scope "/", CalendlexWeb do
      pipe_through :browser

      # ...

      live "/:event_type_slug/:time_slot", ScheduleEventLive
  end
end

# ./lib/calendlex_web/live/schedule_event_live.ex

defmodule CalendlexWeb.ScheduleEventLive do
  use CalendlexWeb, :live_view

  def mount(_params, _session, socket) do
    {:ok, socket}
  end
end

# ./lib/calendlex_web/live/schedule_event_live.html.heex

ScheduleEventLive

After making these changes, everything should compile again, and we should see something similar to the following in the browser:

Booking a new time slot

If we click on any of the available time slots, it takes us to the new live view we just created, in which we have to render the booking form. Let's go ahead and refactor the initial implementation:

# ./lib/calendlex_web/live/schedule_event_live.ex

defmodule CalendlexWeb.ScheduleEventLive do
  use CalendlexWeb, :live_view

  alias Calendlex.Event

  def mount(%{"event_type_slug" => slug, "time_slot" => time_slot}, _session, socket) do
    with {:ok, event_type} <- Calendlex.get_event_type_by_slug(slug),
         {:ok, start_at, _} <- DateTime.from_iso8601(time_slot) do
      end_at = Timex.add(start_at, Timex.Duration.from_minutes(event_type.duration))
      changeset = Event.changeset(%Event{}, %{})

      socket =
        socket
        |> assign(changeset: changeset)
        |> assign(end_at: end_at)
        |> assign(event_type: event_type)
        |> assign(start_at: start_at)

      {:ok, socket}
    else
      _ ->
        {:ok, socket, layout: {CalendlexWeb.LayoutView, "not_found.html"}}
    end
  end
end

Like we did in the previous view, we check if both the event type slug and time slot are correct or render the error page. In the happy path, we create a new Event changeset and assign it to the socket along with event_type, start_at, and end_at. We are going to use this changeset to render the booking form, so let's go ahead and edit the template:

<div class="w-3/5 mx-auto">
  <div class="flex flex-auto p-6 mb-2 bg-white border border-gray-200 shadow-lg rounded-md gap-x-2">
    <div class="flex-1">
      <div class="mb-4">
        <%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.EventTypeLive, @event_type.slug) do %>
          <div>
            <div class="flex items-center justify-center inline-block text-xl text-blue-500 border rounded-full w-9 h-9">
              <i class="fas fa-arrow-left"></i>
            </div>
          </div>
        <% end %>
      </div>
      <h4 class="text-gray-500">Bigardone</h4>
      <h1 class="my-3 text-xl text-black"><%= @event_type.name %></h1>
      <div class="flex flex-row items-center mb-2 font-bold text-gray-500 gap-2">
        <i class="far fa-clock"></i>
        <%= @event_type.duration %> min
      </div>
      <div class="flex flex-row items-center mb-2 font-bold text-green-500 gap-2">
        <i class="far fa-calendar-alt"></i>
        <%= CalendlexWeb.LiveViewHelpers.schedule_string(@start_at, @end_at, @time_zone) %>
      </div>
      <div class="flex flex-row items-center font-bold text-gray-500 gap-2">
        <i class="fas fa-globe-americas"></i>
        <%= @time_zone %>
      </div>
    </div>
    <div class="w-3/5 px-8 border-l border-gray-100">
      <header class="mb-8">
          <h3 class="text-lg font-semibold text-gray-900">Enter details</h3>
      </header>
      <.form let={f} for={@changeset} phx-submit="submit">
        <div class="w-4/5 mb-6">
          <%= label f, :name, class: "block mb-2 text-sm" %>
          <%= text_input f, :name, class: "w-full p-2 border rounded-md", autofocus: "", required: "" %>
          <%= error_tag f, :name %>
        </div>
        <div class="w-4/5 mb-6">
          <%= label f, :email, class: "block mb-2 text-sm" %>
          <%= text_input f, :email, class: "w-full p-2 border rounded-md", type: "email", required: "" %>
          <%= error_tag f, :email %>
        </div>
        <div class="w-4/5 mb-6">
          <%= label f, :comments, class: "block mb-2 text-sm" %>
          <%= textarea f, :comments, class: "w-full p-2 border h-36 rounded-md" %>
        </div>
        <div class="w-4/5 mb-6">
          <button class="px-4 py-2 text-white bg-blue-600 rounded-full" type="submit" phx-disable-with="Scheduling event...">Schedule event</button>
        </div>
      </.form>
    </div>
  </div>
</div>

The template consists of two sections. In the left section, we display the info related to the event type, in which we are formatting the date and time using a schedule_string.schedule_string/3 that we have to add to the CalendlexWeb.LiveViewHelpers module:

# ./lib/calendlex_web/live/live_view_helpers.ex

defmodule CalendlexWeb.LiveViewHelpers do
  # ...

  def schedule_string(start_at, end_at, time_zone) do
    slot_start_str =
      start_at
      |> DateTime.shift_zone!(time_zone)
      |> Timex.format!("{h24}:{m}")

    slot_end_str =
      end_at
      |> DateTime.shift_zone!(time_zone)
      |> Timex.format!("{h24}:{m}")

    date_str =
      start_at
      |> DateTime.shift_zone!(time_zone)
      |> Timex.format!("{WDfull}, {Mfull} {D}, {YYYY}")

    "#{slot_start_str} - #{slot_end_str}, #{date_str}"
  end
end

In the right section of the page, we render the form for the previously assigned changeset. If we jump back to the browser, we should see the new page rendering correctly:

Taking a closer look at the form tag, we can observe two peculiarities:

We are using another function component, .form, from Phoenix.
We have added a phx-submit attribute.

The phx-submit attribute is one of LiveView's form bindings and makes it possible to handle form submissions from our live views. To handle it, we have to implement the proper callback function:

# ./lib/calendlex_web/live/schedule_event_live.ex

defmodule CalendlexWeb.ScheduleEventLive do
  use CalendlexWeb, :live_view

  alias Calendlex.Event

  # ...

  def handle_event(
        "submit",
        %{"event" => event},
        %{
          assigns: %{
            end_at: end_at,
            event_type: event_type,
            start_at: start_at,
            time_zone: time_zone
          }
        } = socket
      ) do
    event
    |> Map.put("end_at", end_at)
    |> Map.put("event_type_id", event_type.id)
    |> Map.put("start_at", start_at)
    |> Map.put("time_zone", time_zone)
    |> Calendlex.insert_event()
    |> case do
      {:ok, event} ->
        {:noreply,
         push_redirect(socket,
           to: Routes.live_path(socket, CalendlexWeb.EventsLive, event_type.slug, event.id)
         )}

      {:error, changeset} ->
        {:noreply, assign(socket, changeset: changeset)}
    end
  end
end

Taking both the form parameters and the socket assigns, we create a map that we pass to Calendlex.insert_event/1 to create the new event. If the event creation is successful, we redirect to the result page. Otherwise, we assign the errored changeset to the socket. Let's take care of the Calendlex functions that we are going to need:

# ./lib/calendlex.ex

defmodule Calendlex do
  # ...

  defdelegate insert_event(params), to: Calendlex.Event.Repo, as: :insert

  defdelegate get_event_by_id(id), to: Calendlex.Event.Repo, as: :get
end

# ./lib/calendlex/event/repo.ex

defmodule Calendlex.Event.Repo do
  alias Calendlex.{Event, Repo}

  def insert(params) do
    %Event{}
    |> Event.changeset(params)
    |> Repo.insert()
  end

  def get(id) do
    Event
    |> Repo.get(id)
    |> Repo.preload(:event_type)
    |> case do
      nil ->
        {:error, :not_found}

      event ->
        {:ok, event}
    end
  end
end

Now we need to add the final result page, so let's edit the routes module and map it:

# ./lib/calendlex_web/router.ex

defmodule CalendlexWeb.Router do
  use CalendlexWeb, :router

  # ...

  live_session :public, on_mount: CalendlexWeb.Live.InitAssigns do
    scope "/", CalendlexWeb do
      pipe_through :browser

      # ...

      live "/events/:event_type_slug/:event_id", EventsLive
    end
  end
end

# ./lib/calendlex_web/live/events_live.ex

defmodule CalendlexWeb.EventsLive do
  use CalendlexWeb, :live_view

  def mount(%{"event_type_slug" => slug, "event_id" => id}, _session, socket) do
    with {:ok, event_type} <- Calendlex.get_event_type_by_slug(slug),
         {:ok, event} <- Calendlex.get_event_by_id(id) do
      socket =
        socket
        |> assign(event_type: event_type)
        |> assign(event: event)

      {:ok, socket}
    else
      {:error, :not_found} ->
        {:ok, socket, layout: {CalendlexWeb.LayoutView, "not_found.html"}}
    end
  end
end

This live view is pretty straightforward. It tries to find the event type and the created event by the incoming params, assigning them to the socket to render the following template:

# ./lib/calendlex_web/live/events_live.html.heex

<div class="w-2/5 mx-auto">
  <div class="flex flex-auto p-12 mb-2 bg-white border border-gray-200 shadow-md rounded-md gap-x-2">
    <div class="flex-1 text-center">
      <header class="mb-8">
        <h1 class="mb-4 text-xl font-bold text-gray-500 text-gray-800">Confirmed</h1>
        <p>You are scheduled with <%= @owner.name %>.</p>
      </header>
      <h2 class="my-3 text-xl font-bold text-gray-800"><%= @event_type.name %></h2>
      <div class="flex flex-row items-center justify-center font-bold text-green-500 gap-2">
        <i class="far fa-calendar-alt"></i>
        <%= CalendlexWeb.LiveViewHelpers.schedule_string(@event.start_at, @event.end_at, @time_zone) %>
      </div>
    </div>
  </div>
</div>

If we jump back to the browser, fill in the form, and submit it, we should see the following:

Yay! We have finally booked our first event. However, we still have one more thing to do: consider the booked events while calculating the available time slots. Let's edit the time slot module and refactor its logic:

# ./lib/calendlex/time_slots.ex

defmodule Calendlex.TimeSlots do
  alias Calendlex.Event.Repo, as: EventRepo

  @spec build(Date.t(), String.t(), non_neg_integer) :: [DateTime.t()]
  def build(date, time_zone, duration) do
    from =
      date
      |> Timex.to_datetime(time_zone)
      |> Timex.set(hour: day_start())

    to = Timex.set(from, hour: day_end())

    # Get the booked events for the given date
    date_events = EventRepo.get_by_start_date(date)

    from
    |> Stream.iterate(&DateTime.add(&1, duration * 60, :second))
    |> Stream.take_while(&(DateTime.diff(to, &1) > 0))
    # Reject time slots overlapping booked events
    |> Stream.reject(&reject_overlaps(&1, date_events, duration))
    |> Enum.to_list()
  end

  # ...

  defp reject_overlaps(time_slot, date_events, duration) do
    next_time_slot = DateTime.add(time_slot, duration * 60, :second)

    Enum.any?(date_events, fn event ->
      if DateTime.compare(event.start_at, time_slot) == :lt do
        DateTime.compare(event.end_at, time_slot) == :gt
      else
        DateTime.compare(event.start_at, next_time_slot) == :lt
      end
    end)
  end
end

We get from the database all the events starting in the given date and remove the time slots overlapping them. Let's implement the get_by_start_date/1 in the event repo module:

# ./lib/calendlex/event/repo.ex

defmodule Calendlex.Event.Repo do
  import Ecto.Query

  alias Calendlex.{Event, Repo}

  # ...

  def get_by_start_date(date) do
    Event
    |> where([e], fragment("?::date", e.start_at) == ^date)
    |> order_by(:start_at)
    |> Repo.all()
  end
end

If we go back to the exact date we just booked the event for, we should see that time slot (09:30) missing in the list:

And that's all for the public side of our application. In the next part, we will start implementing the private admin site. We will use a new live session, protected with Basic HTTP authentication, and implement the event types section, in which we will list all the existing event types, and make use of LiveView's JS commands to create a cool dropdown menu. In the meantime, you can check the final result in the live demo, or have a look at the source code.

Happy coding!

bigardone / calendlex

Simple Calendly clone with Phoenix LiveView

Building a simple Calendly clone with Phoenix LiveView (pt. 4)

Ricardo García Vega — Mon, 29 Nov 2021 05:48:59 +0000

In the last part of the series, we implemented the initial page of the application, which lists all the available event types, letting the visitor select one and transition to the next page that we left empty. To do so, we took advantage of LiveView's features like live sessions and function components. In this part, we will start by implementing all the logic surrounding the empty CalendlexWeb.EventTypeLive live view. We will render a monthly calendar, letting the visitor navigate through the months, and selecting a date. Let's get cracking!

Displaying the initial event type page

Let's start by modifying the CalendlexWeb.EventTypeLive module to load the corresponding event type on its mount callback:

# ./lib/calendlex_web/live/event_type_live.ex

defmodule CalendlexWeb.EventTypeLive do
  use CalendlexWeb, :live_view

  alias CalendlexWeb.Components.EventType

  def mount(%{"event_type_slug" => slug}, _session, socket) do
    case Calendlex.get_event_type_by_slug(slug) do
      {:ok, event_type} ->
        socket =
          socket
          |> assign(event_type: event_type)
          |> assign(page_title: event_type.name)

        {:ok, socket}

      {:error, :not_found} ->
        {:ok, socket, layout: {CalendlexWeb.LayoutView, "not_found.html"}}
    end
  end
end

Taking the event type slug from the parameters received, it calls the Calendlex.get_event_type_by_slug/1 function. If the event type exists, it assigns it to the socket and sets the corresponding page title. On the contrary, it renders a regular error page. Let's first take care of the happy path and implement the Calendlex.get_event_type_by_slug/1 function:

# ./lib/calendlex.ex

defmodule Calendlex
  # ...

  defdelegate get_event_type_by_slug(slug),
    to: Calendlex.EventType.Repo,
    as: :get_by_slug
end

It delegates its call to the Calendlex.EventType.Repo.get_by_slug/1 function. Let's add it:

# ./lib/calendlex/event_type/repo.ex

defmodule Calendlex.EventType.Repo do
  alias Calendlex.{EventType, Repo}

  # ...

  def get_by_slug(slug) do
    case Repo.get_by(EventType, slug: slug) do
      nil ->
        {:error, :not_found}

      event_type ->
        {:ok, event_type}
    end
  end
end

If we start the Phoenix server and visit http://localhost:4000/15-minute-meeting, we should see the empty page correctly. Now let's take care of the error path, and create the not_found layout template:

# ./lib/calendlex_web/templates/layout/not_found.html.heex

<main role="main" class="py-32 mx-auto">
  <div class="w-2/5 mx-auto">
    <div class="px-6 py-12 mb-2 text-center bg-white border border-gray-200 shadow-md rounded-md gap-x-2">
      <header class="mb-8 text-lg font-bold text-gray-900">
        <h2><%= @owner.name %></h2>
        <p>This Calendlex URL is not valid.</p>
      </header>
      <p>If you are the owner of this account, you can log in to find out more.</p>
    </div>
  </div>
</main>

If we visit an invalid URL like http://localhost:4000/invalid-event-type, we should see the following:

Great! Let's edit the CalendlexWeb.EventTypeLive template file and add some initial content:

# ./lib/calendlex_web/live/event_type_live.html.heex

<div class="w-3/5 mx-auto">
  <div class="flex flex-auto p-6 mb-2 bg-white border border-gray-200 shadow-md rounded-md gap-x-2">
    <div class="flex-1">
      <div class="mb-4">
        <%= live_redirect to: Routes.live_path(@socket, CalendlexWeb.PageLive) do %>
          <div class="flex items-center justify-center inline-block text-xl text-blue-500 border rounded-full w-9 h-9">
            <i class="fas fa-arrow-left"></i>
          </div>
        <% end %>
      </div>
      <h4 class="text-gray-500">Bigardone</h4>
      <h1 class="my-3 text-xl text-black"><%= @event_type.name %></h1>
      <div class="flex flex-row items-center mb-2 text-gray-500 gap-2">
        <div class="text-gray-300">
          <i class="far fa-clock"></i>
        </div>
        <%= @event_type.duration %> min
      </div>
    </div>
    <div class="px-8 border-l border-gray-100">
      <header class="mb-8">
          <h3 class="text-lg font-semibold text-gray-900">Select a date & time</h3>
      </header>
    </div>
  </div>
</div>

Once the browser refreshes the page, we should see the following:

Rendering the monthly calendar

With the initial layout ready, let's work on the monthly calendar. Since we will work with dates and times and formatting them, let's use Timex, which is the usual library I use for these cases. To install it, we need to add it to the dependencies in the mix file and run the corresponding mix deps.get command:

# ./mix.exs

defmodule Calendlex.MixProject do
  use Mix.Project

  # ...

  defp deps do
    [
      # ...
      {:timex, "~> 3.7"}
    ]
  end

  # ...
end

Before continuing further, we have to consider the visitor's time zone to handle any date and time. Therefore, we need a way to assign it to the socket. Fortunately for us, this is very straightforward, thanks to JavaScript. Let's edit the main app.js file:

// ./assets/js/app.js

// ...

const liveSocket = new LiveSocket('/live', Socket, {
  params: {
    _csrf_token: csrfToken,
    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
  },
});

// ...

We add a new timezone parameter to the live socket connection with the timeZone value from Intl.DateTimeFormat.prototype.resolvedOptions(), which returns a new object with properties reflecting the current user's browser's locale and date and time. Remember the live public session we created in the previous part? Let's edit it to take into account the timezone parameter:

# ./lib/calendlex_web/live/init_assigns.ex

defmodule CalendlexWeb.Live.InitAssigns do
  import Phoenix.LiveView

  def on_mount(:default, _params, _session, socket) do
    owner = Application.get_env(:calendlex, :owner)
    time_zone = get_connect_params(socket)["timezone"] || owner.time_zone

    socket =
      socket
      |> assign(:owner, owner)
      |> assign(:time_zone, time_zone)

    {:cont, socket}
  end
end

We use get_connect_params/1 to take the value from the socket's connection parameters and assign it to the socket. If timezone does not exist, we set the owner's time zone as the default value. Let's jump back to the CalendlexWeb.EventTypeLive and add the corresponding assigns that we need to build the calendar:

# ./lib/calendlex_web/live/event_type_live.ex

defmodule CalendlexWeb.EventTypeLive do
  alias Calendlex.{EventType, Repo}

  alias Timex.Duration

  def mount(%{"event_type_slug" => slug}, _session, socket) do
    case Calendlex.get_event_type_by_slug(slug) do
      {:ok, event_type} ->
        socket =
          socket
          # ...
          |> assign_dates()

        {:ok, socket}

      # ...
    end
  end

  defp assign_dates(socket) do
    current = Timex.today(socket.assigns.time_zone)
    beginning_of_month = Timex.beginning_of_month(current)
    end_of_month = Timex.end_of_month(current)

    previous_month =
      beginning_of_month
      |> Timex.add(Duration.from_days(-1))
      |> date_to_month()

    next_month =
      end_of_month
      |> Timex.add(Duration.from_days(1))
      |> date_to_month()

    socket
    |> assign(current: current)
    |> assign(beginning_of_month: beginning_of_month)
    |> assign(end_of_month: end_of_month)
    |> assign(previous_month: previous_month)
    |> assign(next_month: next_month)
  end

  defp date_to_month(date_time) do
    Timex.format!(date_time, "{YYYY}-{0M}")
  end
end

In the mount/3 function's happy path, we call a new assign_dates function that takes the socket. This function calculates the current date, the beginning, and the end of the current month and assigns them to the socket. It also assigns the next and previous months with the "{YYYY}-{0M}" format that we will use to navigate through the different months. Let's get back to the view's template and build up the calendar:

# ./lib/calendlex_web/live/event_type_live.html.heex

<div class="w-3/5 mx-auto">
  <div class="flex flex-auto p-6 mb-2 bg-white border border-gray-200 shadow-md rounded-md gap-x-2">
    <div class="flex-1">
        # ...

        <%= @event_type.duration %> min
      </div>
    </div>
    <div class="px-8 border-l border-gray-100">
      <header class="mb-8">
          <h3 class="text-lg font-semibold text-gray-900">Select a date & time</h3>
      </header>
      <EventType.calendar
              id="calendar"
              current_path={Routes.live_path(@socket, CalendlexWeb.EventTypeLive, @event_type.slug)}
              previous_month={@previous_month}
              next_month={@next_month}
              current={@current}
              end_of_month={@end_of_month}
              beginning_of_month={@beginning_of_month}
              time_zone={@time_zone} />
    </div>
  </div>
</div>

We will use a new function component in the already existing CalendlexWeb.Components.EventType module to render the calendar. Let's alias this module in the view and implement the new function:

# ./lib/calendlex/event_type/repo.ex

defmodule Calendlex.EventType.Repo do
  # ...

  alias CalendlexWeb.Components.EventType

  #...
end

# ./lib/calendlex_web/live/components/event_type.ex

defmodule CalendlexWeb.Components.EventType do
  use Phoenix.Component

  # ...

  def calendar(
        %{
          current_path: current_path,
          previous_month: previous_month,
          next_month: next_month
        } = assigns
      ) do
    previous_month_path = build_path(current_path, %{month: previous_month})
    next_month_path = build_path(current_path, %{month: next_month})

    assigns =
      assigns
      |> assign(previous_month_path: previous_month_path)
      |> assign(next_month_path: next_month_path)

    ~H"""
    <div>
      <div class="flex items-center mb-8">
        <div class="flex-1">
          <%= Timex.format!(@current, "{Mshort} {YYYY}") %>
        </div>
        <div class="flex justify-end flex-1 text-right">
          <%= live_patch to: @previous_month_path do %>
            <button class="flex items-center justify-center w-10 h-10 text-blue-700 align-middle rounded-full hover:bg-blue-200">
              <i class="fas fa-chevron-left"></i>
            </button>
          <% end %>
          <%= live_patch to: @next_month_path do %>
            <button class="flex items-center justify-center w-10 h-10 text-blue-700 align-middle rounded-full hover:bg-blue-200">
              <i class="fas fa-chevron-right"></i>
            </button>
          <% end %>
        </div>
      </div>
      <div class="mb-6 text-center uppercase calendar grid grid-cols-7 gap-y-2 gap-x-2">
        <div class="text-xs">Mon</div>
        <div class="text-xs">Tue</div>
        <div class="text-xs">Wed</div>
        <div class="text-xs">Thu</div>
        <div class="text-xs">Fri</div>
        <div class="text-xs">Sat</div>
        <div class="text-xs">Sun</div>
      </div>
      <div class="flex items-center gap-x-1">
        <i class="fas fa-globe-americas"></i>
        <%= @time_zone %>
      </div>
    </div>
    """
  end

  defp build_path(current_path, params) do
    current_path
    |> URI.parse()
    |> Map.put(:query, URI.encode_query(params))
    |> URI.to_string()
  end
end

calendar takes the assigned previous_month and nex_month values to generate the month navigation paths, consisting of current_path with a query string parameter named month with the corresponding value. Why are we doing this? To render a different month in the calendar, we have to update the current, beginning_of_month, and end_of_month assigns. There are two ways of achieving this:

Add a click event on each month's navigation buttons and the corresponding handle_event/3 callback function in the live view.
Use live_patch/2 against the same URL, add any query string parameter we need, and implement the corresponding handle_params/3 callback function in the live view module.

In this particular case, the second option has two winning advantages over the first one. Firstly, handle_params/3 is called right after mount/3 and before the initial render so we can reuse its logic for the initial mount. Secondly, and most important, it also updates the browser's URL, so if the user refreshes the page, all the parameters that we use to build the view's state will not get lost. Let's jump back to the browser and check that we see the following:

Looking good so far. However, if we click on either of the < or > buttons to display a different month, we can see the following error in the terminal:

[error] GenServer #PID<0.617.0> terminating
** (UndefinedFunctionError) function CalendlexWeb.EventTypeLive.handle_params/3 is undefined or private
    (calendlex 0.1.0) CalendlexWeb.EventTypeLive.handle_params(%{"event_type_slug" => "15-minute-meeting", "month" => "2021-12"}, "http://localhost:4000/15-minute-meeting?month=2021-12", #Phoenix.LiveView.Socket<assigns: %{__changed__: %{}, beginning_of_month: ~D[2021-11-01], current: ~D[2021-11-26], end_of_month: ~D[2021-11-30], event_type: %Calendlex.EventType{__meta__: #Ecto.Schema.Metadata<:loaded, "event_types">, color: "blue", description: "Short meeting call.", duration: 15, id: "51bd2b10-783f-42f5-bc89-57e4253d0127", inserted_at: ~N[2021-11-23 07:17:59], name: "15 minute meeting", slug: "15-minute-meeting", updated_at: ~N[2021-11-23 07:17:59]}, flash: %{}, live_action: nil, next_month: "2021-12", owner: %{name: "Bigardone", time_zone: "Europe/Madrid"}, page_title: "15 minute meeting", previous_month: "2021-10", time_slots: [], time_zone: "Europe/Madrid"}, endpoint: CalendlexWeb.Endpoint, id: "phx-FrsEfVWph4A5eQCE", parent_pid: nil, root_pid: #PID<0.617.0>, router: CalendlexWeb.Router, transport_pid: #PID<0.611.0>, view: CalendlexWeb.EventTypeLive, ...>)
    (phoenix_live_view 0.17.5) lib/phoenix_live_view/utils.ex:369: anonymous fn/5 in Phoenix.LiveView.Utils.call_handle_params!/5
    (telemetry 1.0.0) /Users/ricardogarciavega/projects/elixir/calendlex/deps/telemetry/src/telemetry.erl:293: :telemetry.span/3
    (phoenix_live_view 0.17.5) lib/phoenix_live_view/channel.ex:117: Phoenix.LiveView.Channel.handle_info/2
    (stdlib 3.15) gen_server.erl:695: :gen_server.try_dispatch/4
    (stdlib 3.15) gen_server.erl:771: :gen_server.handle_msg/6
    (stdlib 3.15) proc_lib.erl:226: :proc_lib.init_p_do_apply/3

To fix the error, we must implement the handle_params/3 callback in the CalendlexWeb.EventTypeLive module:

# ./lib/calendlex_web/live/event_type_live.ex

defmodule CalendlexWeb.EventTypeLive do
  use CalendlexWeb, :live_view

  alias CalendlexWeb.Components.EventType

  def mount(%{"event_type_slug" => slug}, _session, socket) do
    case Calendlex.get_event_type_by_slug(slug) do
      {:ok, event_type} ->
        socket =
          socket
          |> assign(event_type: event_type)
          |> assign(page_title: event_type.name)
          # we remove this line
          # |> assign_dates()

        {:ok, socket}

      {:error, :not_found} ->
        {:ok, socket, layout: {CalendlexWeb.LayoutView, "not_found.html"}}
    end
  end

  def handle_params(params, _uri, socket) do
    # we call `assign_dates` passing `params` as well
    socket = assign_dates(socket, params)

    {:noreply, socket}
  end

  # this function now accepts an additional parameter `params`
  defp assign_dates(socket, params) do
    current = current_from_params(socket, params)

    # ...
  end

  defp current_from_params(socket, %{"month" => month}) do
    case Timex.parse("#{month}-01", "{YYYY}-{0M}-{D}") do
      {:ok, current} ->
        NaiveDateTime.to_date(current)

      _ ->
        Timex.today(socket.assigns.time_zone)
    end
  end

  defp current_from_params(socket, _) do
    Timex.today(socket.assigns.time_zone)
  end

  # ...
end

We have made four changes to the current module's logic:

First of all, since handle_params/3 gets called right after mount/3, we don't need to call assign_dates/2 from mount, so we can remove the call.
We have implemented the handle_params/3 callback function, which calls assign_dates/2 passing the socket and the parameters received in the request.
We have added a new parameter, params, to the assign_dates function that we use to calculate the value of current.
Last but not least, we have added a new current_from_params/2 function which takes the socket and the parameters and builds current.

If we go back to the browser and click again on the previous and next month buttons, we should see how the URL in the browser updates, rendering the corresponding month. Moreover, if we now refresh the browser, it doesn't lose track of the month we were displaying. Yay!

Our calendar is almost ready. The only thing left is rendering the month's days. Let's jump back to the CalendlexWeb.Components.EventType.calendar/1 function component and implement the corresponding logic:

# ./lib/calendlex_web/live/components/event_type.ex

defmodule CalendlexWeb.Components.EventType do
  use Phoenix.Component

  # We will implement this module in a minute...
  import CalendlexWeb.LiveViewHelpers

  alias __MODULE__

  # ...

  def calendar(
        %{
          current_path: current_path,
          previous_month: previous_month,
          next_month: next_month
        } = assigns
      ) do
    # ...

    ~H"""
    <div>
      # ...

      <div class="mb-6 text-center uppercase calendar grid grid-cols-7 gap-y-2 gap-x-2">
        <div class="text-xs">Mon</div>
        <div class="text-xs">Tue</div>
        <div class="text-xs">Wed</div>
        <div class="text-xs">Thu</div>
        <div class="text-xs">Fri</div>
        <div class="text-xs">Sat</div>
        <div class="text-xs">Sun</div>
        <%= for i <- 0..@end_of_month.day - 1 do %>
          <EventType.day
            index={i}
            current_path={@current_path}
            date={Timex.shift(@beginning_of_month, days: i)}
            time_zone={@time_zone} />
        <% end %>
      </div>
      # ...
    </div>
    """
  end

  # ...

  def day(%{index: index, current_path: current_path, date: date, time_zone time_zone} = assigns) do
    date_path = build_path(current_path, %{date: date})
    disabled = Timex.compare(date, Timex.today(time_zone)) == -1
    weekday = Timex.weekday(date, :monday)

    class =
      class_list([
        {"grid-column-#{weekday}", index == 0},
        {"content-center w-10 h-10 rounded-full justify-center items-center flex", true},
        {"bg-blue-50 text-blue-600 font-bold hover:bg-blue-200", not disabled},
        {"text-gray-200 cursor-default pointer-events-none", disabled}
      ])

    assigns =
      assigns
      |> assign(disabled: disabled)
      |> assign(:text, Timex.format!(date, "{D}"))
      |> assign(:date_path, date_path)
      |> assign(:class, class)

    ~H"""
    <%= live_patch to: @date_path, class: @class, disabled: @disabled do %>
      <%= @text %>
    <% end %>
    """
  end
end

To display the days, we loop through the number of days in the current month, invoking a new function component called day/1 assigning it the following values:

index: the current index in the loop.
current_path: the current LiveView's path.
date: the current date in the loop.
time_zone: the visitor's time zone.

The component consists of a link pointing to the current path, adding a new query string parameter called date. If the date is before today, we disable the link to prevent scheduling events in the past. Since we want to style the link depending on different factors, we will use a new helper module to generate the class attribute's value. Let's go ahead and create the helper module:

# ./lib/calendlex_web/live/live_view_helpers.ex

defmodule CalendlexWeb.LiveViewHelpers do
  def class_list(items) do
    items
    |> Enum.reject(&(elem(&1, 1) == false))
    |> Enum.map(&elem(&1, 0))
    |> Enum.join(" ")
  end
end

class_list/1 takes a list of two-element tuples, where the first element is a string containing some class names, and the second is a boolean value representing whether it should apply the classes or not. It goes through all the items in the list, rejecting the falsy ones and concatenating the remaining ones. For our day component, we want to add certain styles only when it is the first day of the month, others when it is disabled or not, and we have some common styles as well. "grid-column-#{weekday}" is a custom class that we use to position the first day of the month using CSS Grid Layout, so let's add it to the main CSS file:

/* ./assets/css/app.css */

/* ... */

.grid-column-1 {
  grid-column: 1;
}

.grid-column-2 {
  grid-column: 2;
}

.grid-column-3 {
  grid-column: 3;
}

.grid-column-4 {
  grid-column: 4;
}

.grid-column-5 {
  grid-column: 5;
}

.grid-column-6 {
  grid-column: 6;
}

.grid-column-7 {
  grid-column: 7;
}

Jumping back to the browser, we should see our calendar in all its glory:

We should see how the calendar updates, rendering the new month's days if we navigate through the months. There's only one thing left to do: handle the new date parameter on the live patch invoked when we click on a date:

# ./lib/calendlex_web/live/event_type_live.ex

defmodule CalendlexWeb.EventTypeLive do
  use CalendlexWeb, :live_view

  # ...

  defp current_from_params(socket, %{"date" => date}) do
    case Timex.parse(date, "{YYYY}-{0M}-{D}") do
      {:ok, current} ->
        NaiveDateTime.to_date(current)

      _ ->
        Timex.today(socket.assigns.time_zone)
    end
  end

  # ...
end

Since we previously left everything ready when we implemented the month parameter, we only have to add a new version of the current_from_params function for the date parameter and set it as the current date. If we now click on a date, we should see how the browser's URL updates adding the date parameter, and if we refresh the browser's page, the calendar should render on the date we selected:

That's it for this part. In the next part, we will use the event type and date selected by the user to render all the available time slots in the day. We will also implement the schedule event live view, creating a new event once the visitor submits its form. In the meantime, you can check the end result in the live demo, or have a look at the source code.

Happy coding!

bigardone / calendlex

Simple Calendly clone with Phoenix LiveView

Building a simple Calendly clone with Phoenix LiveView (pt. 3)

Ricardo García Vega — Thu, 18 Nov 2021 14:53:48 +0000

In the last part of the series, we generated a new Phoenix project and made the necessary changes to support Tailwind CSS. We also defined our domain models, consisting of event types and events, generating their migration files and Ecto schemas. Finally, we populated the database with three event types using the seeds file. In this part we will start building the public part of our application, in which a visitor will select one of them, a date, and a starting time, to schedule an event with us. More precisely, we will focus on the event type selection page, taking advantage of two new LiveView features:

Live sessions.
Function components.

Let's get cracking!

But before, let's recall how LiveView works

If you are already familiar with LiveView and how it works, you can skip this part and jump to the next section. Otherwise, hold your horses and read this section before continuing, since understanding how LiveView works internally will help you a lot while coding. Any LiveView begins as a regular HTTP request with a standard HTML response. When the initial HTML response renders in the browser, LiveView's JS client opens a Phoenix socket connection between the page and the application. This socket connection is nothing more than a process that stores a state and receives messages to update this state. Every time its internal state (a.k.a assigns) changes, LiveView re-rerenders the relevant parts of its HTML, pushing back the changes through the socket to the browser, where the JS client efficiently applies the changes to the DOM. The most remarkable thing about this is that LiveView guarantees a first HTML response render, whether JavaScript is enabled or not, which is very convenient for indexing, SEO, etc.

The public live session

Live session is one of the new features added by LiveView. It defines a group of live routes that can handle navigation between them through the socket without any additional HTTP request to the server. It can share the same root layout and list of hooks to attach to the mount lifecycle of the LiveView. Very handy when you need to assign the same data to the socket over and over within a group of live views. In our case, as the owners of the calendar, we want to display our name to the visitor. Let's add it to our application configuration:

# ./config/config.exs

import Config

config :calendlex,
  # ...
  owner: %{
    name: "Bigardone"
  }

# ...

Now let's create the :public live session in the router file:

# ./lib/calendlex_web/router.ex

defmodule CalendlexWeb.Router do
  use CalendlexWeb, :router

  # ...

  live_session :public, on_mount: CalendlexWeb.Live.InitAssigns do
    scope "/", CalendlexWeb do
      pipe_through :browser

      live "/", PageLive
    end
  end
end

To assign the :owner configuration to the socket of all the live views within the :public live session, we will use the new module specified in the :on_mount option. Let's create it:

# ./lib/calendlex_web/live/init_assigns.ex

defmodule CalendlexWeb.Live.InitAssigns do
  import Phoenix.LiveView

  def on_mount(:default, _params, _session, socket) do
    owner = Application.get_env(:calendlex, :owner)
    socket = assign(socket, :owner, owner)

    {:cont, socket}
  end
end

Live session hooks must implement the on_mount callback, which receives the identifier of the hook (to use pattern matching in case we want to define multiple versions), the public parameters, the session, and the socket. We get the owner's data from the application's configuration, assign it to the socket, and return {:cont, socket} to continue with LiveView's flow. With the owner's data available on every live view within the public session, we can move on and implement our first live view.

The event type selection page

This page will get rendered in the application's root path, and it will list all the available event types, letting the user select one, which will trigger a redirection to the next page.

Let's start by editing the PageLive module we created in the previous part:

# ./lib/calendlex_web/live/page_live.ex

defmodule CalendlexWeb.PageLive do
  use CalendlexWeb, :live_view

  # We will implement this module in a minute...
  alias CalendlexWeb.Components.EventType

  def mount(_params, _session, socket) do
    event_types = Calendlex.available_event_types()

    {:ok, assign(socket, event_types: event_types), temporary_assigns: [event_types: []]}
  end
end

When a LiveView gets rendered, the mount/3 callback is invoked, and it accepts the private session and some public params. In this callback, we can fetch the necessary data we want to render. Therefore, we are getting all the available event types from the database and assigning them to the socket to render them in the template. We are also returning the temporary_assigns option, which sets the event_types assign to an empty list after rendering the template, preventing possible memory issues when having big lists of items. Calendlex.available_event_types/0 does not exist yet, so let's go ahead and implement it:

# ./lib/calendlex.ex

defmodule Calendlex do
  defdelegate available_event_types, to: Calendlex.EventType.Repo, as: :available
end

We will use the Calendlex module as the public interface between the CalendlexWeb.* and Calendlex.* namespaces. This way, the presentation layer, or CalenlexWeb.*, does not have to know any implementation details or internals of the business logic, or Calendlex.*. The module exposes an available_event_types/0 function which delegates to the proper internal module in charge of doing any CRUD action related to event types, the Calendlex.EventType.Repo. Let's go ahead and create this module:

# ./lib/calendlex/event_type/repo.ex

defmodule Calendlex.EventType.Repo do
  alias Calendlex.{EventType, Repo}
  import Ecto.Query, only: [order_by: 3]

  def available do
    EventType
    |> order_by([e], e.name)
    |> Repo.all()
  end
end

The available function is pretty straightforward. It gets all the event types from the database ordered by name. We have two different alternatives to render them in the PageLive live view. One is by implementing the render/1 callback function in the same LiveView module, and the other is creating a new template file, like we did in the previous part. I usually prefer the second option, so let's go ahead and modify the template file:

# ./lib/calendlex_web/live/page_live.html.heex

<section class="w-1/2 mx-auto">
  <div class="p-6 mb-2 bg-white border border-gray-200 shadow-md rounded-md">
    <header class="w-2/5 mx-auto mb-12 text-center">
      <h1 class="mb-5 text-xl font-semibold text-gray-500"><%= @owner.name %></h1>
      <p class="text-gray-500">Welcome to my scheduling page. Please follow the instructions to add an event to my calendar.</p>
    </header>
    <div class="mt-4 grid grid-cols-2 gap-x-6">
      <%= for event_type <- @event_types do %>
        <EventType.selector event_type={event_type} path={Routes.live_path(@socket, CalendlexWeb.EventTypeLive, event_type.slug)} />
      <% end %>
    </div>
  </div>
</section>

We refer to the owner's name value, <%= @owner.name %>, previously assigned in the CalendlexWeb.Live.InitAssigns.on_mount/4 hook. To render the available event types, we go through the list of element_types assigned to the socket, and we invoke one of the new features added to LiveView, function components. Thanks to the new HEEx HTML engine introduced by LiveView 0.16, we can now invoke these components using regular HTML tags, which is very convenient and reminds me of React.

The EventType selector function component

Function components, or stateless components, are regular functions that must receive an assigns parameter and return a ~H sigil with the HTML to render. They can't handle any messages, or hold any internal state whatsoever. Let's create the component's module:

# ./lib/calendlex_web/live/components/event_type.ex

defmodule CalendlexWeb.Components.EventType do
  use Phoenix.Component

  def selector(assigns) do
    ~H"""
    <%= live_redirect to: @path do %>
      <div class="flex items-center p-6 pb-20 text-gray-400 bg-white border-t border-gray-300 cursor-pointer hover:bg-gray-200 gap-x-4">
        <div {[class: "inline-block w-8 h-8 #{@event_type.color}-bg rounded-full border-2 border-white"]}></div>
        <h3 class="font-bold text-gray-900"><%= @event_type.name %></h3>
        <div class="ml-auto text-xl"><i class="fas fa-caret-right"></i></div>
      </div>
    <% end %>
    """
  end
end

Since we are calling EventType.event_type, from the PageLive template, setting the event_type and path attributes, these values are automatically assigned and available in the ~H sigil.
If we check the terminal, we should see the following error, caused by the path value which corresponds to an unexisting live path value:

[error] #PID<0.564.0> running CalendlexWeb.Endpoint (connection #PID<0.555.0>, stream id 4) terminated
Server: localhost:4000 (http)
Request: GET /
** (exit) an exception was raised:
    ** (ArgumentError) no action CalendlexWeb.EventTypeLive for CalendlexWeb.Router.Helpers.live_path/3. The following actions/clauses are supported:

    live_path(conn_or_endpoint, CalendlexWeb.PageLive, params \\ [])

To fix the error, let's add the corresponding live path to the router:

# ./lib/calendlex_web/router.ex

defmodule CalendlexWeb.Router do
  use CalendlexWeb, :router

  # ...

  live_session :public, on_mount: CalendlexWeb.Live.InitAssigns do
    scope "/", CalendlexWeb do
      # ...

      live "/:event_type_slug", EventTypeLive
    end
  end

And finally, let's add the corresponding empty LiveView module and template:

# ./lib/calendlex_web/live/event_type_live.ex

defmodule CalendlexWeb.EventTypeLive do
  use CalendlexWeb, :live_view

  def mount(%{"event_type_slug" => _slug} = params, _session, socket) do
    {:ok, socket}
  end
end

<!-- ./lib/calendlex_web/live/event_type_live.html.heex -->

<h1>EventTypeLive</h1>

Jumping back to the browser, we should see the following:

To give the finishing touches to the layout and styling, copy the contents of the main CSS file and paste it into your local version, and replace the content of the root and live layouts with the following:

<!-- ./lib/calendlex_web/templates/layout/root.html.heex -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <%= csrf_meta_tag() %>
    <%= live_title_tag assigns[:page_title] || assigns[:owner][:name], suffix: " · Calendlex" %>
    <link phx-track-static rel="stylesheet" href={Routes.static_path(@conn, "/assets/app.css")}/>
    <script defer phx-track-static type="text/javascript" src={Routes.static_path(@conn, "/assets/app.js")}></script>
    <script src="https://kit.fontawesome.com/9539f8cd16.js" crossorigin="anonymous"></script>
  </head>
  <body class="antialiased text-gray-600 bg-gray-100">
    <div class="flex flex-col h-screen">
      <%= @inner_content %>
    </div>
  </body>
</html>

<!-- ./lib/calendlex_web/templates/layout/live.html.heex -->

<main role="main" class="flex-1 pt-20">
  <p class="alert alert-info" role="alert"
    phx-click="lv:clear-flash"
    phx-value-key="info"><%= live_flash(@flash, :info) %></p>

  <p class="alert alert-danger" role="alert"
    phx-click="lv:clear-flash"
    phx-value-key="error"><%= live_flash(@flash, :error) %></p>

  <%= @inner_content %>
</main>

After the browser refreshes the page, everything should look much nicer.

And that's it for today. In the following part, we will take care of the EventType live view, rendering the monthly calendar, in which the visitor will be able to select a date and a free time slot to schedule an event with us. We will take advantage of more LiveView's features, such as live components and patching the current navigation. In the meantime, you can check the end result in the live demo, or have a look at the source code.

Happy coding!

bigardone / calendlex

Simple Calendly clone with Phoenix LiveView

Building a simple Calendly clone with Phoenix LiveView (pt. 2)

Ricardo García Vega — Wed, 10 Nov 2021 07:25:22 +0000

In this part, we will generate our new project from scratch, using Phoenix v1.6. The most significant change of this version is the removal of webpack and npm dependencies, relying on esbuild to build assets. Nevertheless, we will use Tailwind CSS for styling the HTML, so we will have to make some minor tweaks to the project's default configuration to support it. Finally, we will generate the migration files and schemas for the domain models. Let's get cracking!

Generating the project

First of all, let's ensure that we have the latest version of the Phoenix project generator:

❯ mix archive.install hex phx_new
Resolving Hex dependencies...
Dependency resolution completed:
New:
  phx_new 1.6.2
* Getting phx_new (Hex package)
All dependencies are up to date
Compiling 11 files (.ex)
Generated phx_new app
Generated archive "phx_new-1.6.2.ez" with MIX_ENV=prod
Found existing entry: /Users/ricardogarciavega/.asdf/installs/elixir/1.12.3/.mix/archives/phx_new-1.6.2
Are you sure you want to replace it with "phx_new-1.6.2.ez"? [Yn]
* creating /Users/ricardogarciavega/.asdf/installs/elixir/1.12.3/.mix/archives/phx_new-1.6.2

With the latest version installed, we can run the following command to generate the new project:

mix phx.new calendlex --no-gettext --no-dashboard --no-mailer

We are removing gettext, the live dashboard, and the mailer since we will not use them in this series. After the generator finishes scaffolding all the project files and installing all the initial dependencies, let's make the necessary changes to support Tailwind CSS.

Adding Tailwind CSS support

I've been using Tailwind CSS for quite some time, and I couldn't be happier with it. However, since Phoenix has removed npn and webpack, adding extra front-end dependencies, such as Tailwind CSS, needs some additional changes in the project. After doing a quick search over the Internet, I found this great post from Sergio Tapia that explains how to achieve this task in seven simple steps. Here's the TL;DR version:

1. Install Tailwind CSS

❯ cd assets
❯ npm init -y
❯ npm install tailwindcss postcss postcss-import autoprefixer --save-dev

2. Configure PostCSS

/* ./assets/postcss.config.js */

module.exports = {
  plugins: [
    require('postcss-import')(),
    require('tailwindcss')('./tailwind.config.js'),
    require('autoprefixer'),
  ],
};

3. Configure Tailwind CSS

/* ./assets/tailwind.config.js */

module.exports = {
  mode: 'jit',
  purge: [
    './js/**/*.js',
    './css/**/*.css',
    '../lib/*_web/**/*.*ex',
  ],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

4. Include Tailwind CSS in our styles

/* ./assets/css/app.css */

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

5. Add a watcher for the development environment

# ./config/dev.exs

import Config

# ...

config :calendlex, CalendlexWeb.Endpoint,
  # ...
  watchers: [
    esbuild: {Esbuild, :install_and_run, [:default, ~w(--sourcemap=inline --watch)]},
    npx: [
      "tailwindcss",
      "--input=css/app.css",
      "--output=../priv/static/assets/app.css",
      "--postcss",
      "--watch",
      cd: Path.expand("../assets", __DIR__)
    ]
  ]

# ...

6. Add a deploy script in the package file

// assets/package.json

{
  ...,
  "scripts": {
    "deploy": "NODE_ENV=production postcss css/app.css -o ../priv/static/assets/app.css"
  },
  ...,
}

7. Modify the assets deploy alias in the mix file

# ./mix.exs

defmodule Calendlex.MixProject do
  use Mix.Project

  # ...

  defp aliases do
    [
      # ...
      "assets.deploy": [
        "cmd --cd assets npm run deploy",
        "esbuild default --minify",
        "phx.digest"
      ]
    ]
  end
end

And that's pretty much it. If we start the Phoenix server and visit http://localhost:4000/ we should see the default Phoenix home page rendering.

❯ iex -S mix phx.server
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

[info] Running CalendlexWeb.Endpoint with cowboy 2.9.0 at 127.0.0.1:4000 (http)
[info] Access CalendlexWeb.Endpoint at http://localhost:4000
Interactive Elixir (1.12.3) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> [watch] build finished, watching for changes...

warn - You have enabled the JIT engine which is currently in preview.
warn - Preview features are not covered by semver, may introduce breaking changes, and can change at any time.

Rebuilding...
Done in 145ms.

To confirm that Tailwind is working fine, let's change the color of the body node in the root template:

<% # lib/calendlex_web/templates/layout/root.html.heex %>

<!DOCTYPE html>
<html lang="en">
  ...
  <body class="text-red-500">
    ...
    <%= @inner_content %>
  </body>
</html>

After applying the change, we should see the following in our browser:

Replacing the default controller with a live view

This project will be a full LiveView application, meaning that it will not have regular Phoenix controllers as such, and it will use LiveView to handle all its routes and navigation between them. Therefore, we can remove the default controller that Phoenix generates and all the related files. Let's go ahead and run the following command from the terminal:

rm lib/calendlex_web/views/page_view.ex test/calendlex_web/views/page_view_test.exs lib/calendlex_web/controllers/page_controller.ex test/calendlex_web/controllers/page_controller_test.exs lib/calendlex_web/templates/page/index.html.heex

Now let's create a new live view module and its corresponding rendering template:

# ./lib/calendlex_web/live/page_live.ex

defmodule CalendlexWeb.PageLive do
  use CalendlexWeb, :live_view

  @impl true
  def mount(_params, _session, socket) do
    {:ok, socket}
  end
end

# ./lib/calendlex_web/live/page_live.html.heex

Hello from Calendlex!

We also have to modify the router file to map the root path to the module we just created:

# ./lib/calendlex_web/router.ex

defmodule CalendlexWeb.Router do
  use CalendlexWeb, :router

  # ...

  scope "/", CalendlexWeb do
    pipe_through :browser

    live "/", PageLive
  end
end

Last but not least, let's modify the root template again, removing all the auto-generated Phoenix HTML, rendering only the @inner_content assign inside the body tag:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <%= csrf_meta_tag() %>
    <%= live_title_tag assigns[:page_title] || "Calendlex", suffix: " · Calendlex" %>
    <link phx-track-static rel="stylesheet" href={Routes.static_path(@conn, "/assets/app.css")}/>
    <script defer phx-track-static type="text/javascript" src={Routes.static_path(@conn, "/assets/app.js")}></script>
  </head>
  <body>
    <%= @inner_content %>
  </body>
</html>

Jumping back to the browser, we only should see a white page rendering the Hello from Calendlex! text. Yay!

Defining our domain models

With our initial project configured and ready to start coding, let's move forward and define our domain models. In this tutorial, we are going to focus primarily on two different concerns:

Scheduling invitee events of a given event type.
Managing scheduled events and event types.

Therefore, we can quickly identify two different entities:

1. EventType

It defines the type of a scheduled event, including the event's name, a short description, the path slug that we will use to create friendly URLs, the duration of the event in minutes, and a color to identify an event visually. Let's run the corresponding mix task to generate Ecto's migration file and schema:

❯ mix phx.gen.schema EventType event_types
* creating lib/calendlex/event_type.ex
* creating priv/repo/migrations/20211109085811_create_event_types.exs

Remember to update your repository by running migrations:

    $ mix ecto.migrate

Let's jump into the generated migration file to add all the necessary fields that we need:

# priv/repo/migrations/20211004061942_create_event_types.exs

defmodule Calendlex.Repo.Migrations.CreateEventTypes do
  use Ecto.Migration

  def change do
    create table(:event_types, primary_key: false) do
      add :id, :binary_id, primary_key: true
      add :name, :string, null: false
      add :description, :text
      add :slug, :string, null: false
      add :duration, :integer, null: false
      add :color, :string, null: false

      timestamps()
    end

    create(unique_index(:event_types, [:slug]))
  end
end

Since we eventually want to access the schedule event page using a friendly URL generated with an event type's slug, we are adding a unique index to the slug column. We also need to update the generated schema file to map the fields:

# ./lib/calendlex/event_type.ex

defmodule Calendlex.EventType do
  use Ecto.Schema
  import Ecto.Changeset

  alias __MODULE__

  @primary_key {:id, :binary_id, autogenerate: true}
  @foreign_key_type :binary_id

  schema "event_types" do
    field :description, :string
    field :duration, :integer
    field :name, :string
    field :slug, :string
    field :color, :string

    timestamps()
  end

  @fields ~w(name description slug duration color)a
  @required_fields ~w(name slug duration color)a

  def changeset(event_type \\ %EventType{}, attrs) do
    event_type
    |> cast(attrs, @fields)
    |> validate_required(@required_fields)
    |> unique_constraint(:slug, name: "event_types_slug_index")
  end
end

Note how we add the unique_constraint check in the changeset to prevent runtime errors and convert them into validation errors while inserting/updating event types with existing slugs.

2. Event

It represents a scheduled event type by an invitee. It consists of a previously defined event type, the invitee's name, email, time zone, when the event starts and ends, and any additional comments provided by the invitee while scheduling the event. Let's generate both the migration and schema files like we did before:

❯ mix phx.gen.schema Event events
* creating lib/calendlex/event.ex
* creating priv/repo/migrations/20211109091909_create_events.exs

Remember to update your repository by running migrations:

    $ mix ecto.migrate

Let's edit the migration file to add the necessary columns:

# ./priv/repo/migrations/20211005043236_create_events.exs

defmodule Calendlex.Repo.Migrations.CreateEvents do
  use Ecto.Migration

  def change do
    create table(:events, primary_key: false) do
      add :id, :binary_id, primary_key: true
      add :start_at, :utc_datetime, null: false
      add :end_at, :utc_datetime, null: false
      add :name, :string, null: false
      add :email, :string, null: false
      add :time_zone, :string, null: false
      add :comments, :text

      add :event_type_id, references(:event_types, on_delete: :nothing, type: :binary_id),
        null: false

      timestamps()
    end

    create index(:events, [:event_type_id])
  end
end

And again, we need to edit the generated schema module to add all the fields:

# ./lib/calendlex/event.ex

defmodule Calendlex.Event do
  use Ecto.Schema
  import Ecto.Changeset

  alias __MODULE__
  alias Calendlex.EventType

  @primary_key {:id, :binary_id, autogenerate: true}
  @foreign_key_type :binary_id

  schema "events" do
    field :comments, :string
    field :email, :string
    field :end_at, :utc_datetime
    field :name, :string
    field :start_at, :utc_datetime
    field :time_zone, :string

    belongs_to(:event_type, EventType)

    timestamps()
  end

  @fields ~w(event_type_id start_at end_at name email comments time_zone)a
  @required_fields ~w(start_at end_at name email time_zone)a

  @doc false
  def changeset(event \\ %Event{}, attrs) do
    event
    |> cast(attrs, @fields)
    |> validate_required(@required_fields)
  end
end

Now we can run the migration task to create the tables in the database:

❯ mix ecto.migrate

10:27:32.009 [info]  == Running 20211109085811 Calendlex.Repo.Migrations.CreateEventTypes.change/0 forward

10:27:32.012 [info]  create table event_types

10:27:32.019 [info]  create index event_types_slug_index

10:27:32.023 [info]  == Migrated 20211109085811 in 0.0s

10:27:32.057 [info]  == Running 20211109091909 Calendlex.Repo.Migrations.CreateEvents.change/0 forward

10:27:32.057 [info]  create table events

10:27:32.064 [info]  create index events_event_type_id_index

10:27:32.065 [info]  == Migrated 20211109091909 in 0.0s

Seeding the database

We can do one last thing before starting to code: insert some initial data in the database. Let's edit the seeds file and create three different event types:

# ./priv/repo/seeds.exs

alias Calendlex.{EventType, Repo}

Repo.delete_all(EventType)

event_types = [
  %{
    name: "15 minute meeting",
    description: "Short meeting call.",
    slug: "15-minute-meeting",
    duration: 15,
    color: "blue"
  },
  %{
    name: "30 minute meeting",
    description: "Extended meeting call.",
    slug: "30-minute-meeting",
    duration: 30,
    color: "pink"
  },
  %{
    name: "Pair programming session",
    description: "One hour of pure pair programming fun!",
    slug: "pair-programming-session",
    duration: 60,
    color: "purple"
  }
]

for event_type <- event_types do
  event_type
  |> EventType.changeset()
  |> Repo.insert!()
end

Let's run the proper mix task to create the data:

❯ mix run priv/repo/seeds.exs
[debug] QUERY OK source="event_types" db=2.4ms queue=0.5ms idle=16.7ms
DELETE FROM "event_types" AS e0 []
[debug] QUERY OK db=2.3ms queue=0.9ms idle=75.1ms
INSERT INTO "event_types" ("color","description","duration","name","slug","inserted_at","updated_at","id") VALUES ($1,$2,$3,$4,$5,$6,$7,$8) ["blue", "Short meeting call.", 15, "15 minute meeting", "15-minute-meeting", ~N[2021-11-09 09:50:35], ~N[2021-11-09 09:50:35], <<189, 68, 59, 71, 130, 177, 79, 169, 145, 17, 62, 233, 57, 10, 95, 6>>]
[debug] QUERY OK db=1.1ms queue=0.9ms idle=81.4ms
INSERT INTO "event_types" ("color","description","duration","name","slug","inserted_at","updated_at","id") VALUES ($1,$2,$3,$4,$5,$6,$7,$8) ["pink", "Extended meeting call.", 30, "30 minute meeting", "30-minute-meeting", ~N[2021-11-09 09:50:35], ~N[2021-11-09 09:50:35], <<146, 45, 139, 50, 20, 126, 68, 211, 147, 21, 28, 64, 65, 236, 162, 119>>]
[debug] QUERY OK db=0.7ms queue=0.4ms idle=83.8ms
INSERT INTO "event_types" ("color","description","duration","name","slug","inserted_at","updated_at","id") VALUES ($1,$2,$3,$4,$5,$6,$7,$8) ["purple", "One hour of pure pair programming fun!", 60, "Pair programming session", "pair-programming-session", ~N[2021-11-09 09:50:35], ~N[2021-11-09 09:50:35], <<192, 218, 73, 37, 143, 124, 73, 97, 162, 109, 198, 169, 219, 186, 112, 251>>]

And that's it for this part. Our initial project is ready to let the fun part begin. In the next part, we will start implementing the public side of our application, in which the visitor will have to select an event type and a suitable date and time slot to schedule a meeting. In the meantime, you can check the end result here, or have a look at the source code.

Happy coding!

bigardone / calendlex

Simple Calendly clone with Phoenix LiveView

Building a simple Calendly clone with Phoenix LiveView (pt. 1)

Ricardo García Vega — Mon, 08 Nov 2021 06:02:25 +0000

Motivation

I've been using Elixir and Phoenix for the last six years to build from APIs to complete web applications using React and Elm on the front-end, being Elm my weapon of choice primarily. Since LiveView came out, I have played around with it a couple of times, first to build an ant farm and second to set up a headless CMS. However, I never ended up getting hooked by it, and I kept relying on Elm to build my front-ends. But when Phoenix v1.6 and LiveView v0.17 came out, my feelings about LiveView changed utterly, and I couldn't resist making something more extensive to test out all its new features, making me finally understand all of its power.

Why Calendly?

When I want to dive deep into new technology, I like building a small clone of a popular service to see how far I can get with it. Scheduling services like Calendly have become very popular, and often people share their public calendar links so others can select the ideal date and time for a meeting. Therefore, after examining its UI, I thought it would be a fun pet project and an excellent tutorial to share.

What are we going to build?

Since Calendly has tons of features, and this tutorial is about Phoenix LiveView, we will focus on its core, which is managing even types and scheduling events. Our application will consist of two different parts:

The sharable public page where invitees can select an event type, a date, and a slot to schedule a meeting with us.
The private admin site, protected by Basic HTTP authentication, where we can create and edit event types and manage all the scheduled events.

Regarding LiveView, we are going to rely on some of its more powerful features such as:

Live sessions.
Live components.
Function components.
JS hooks.
JS commands.

Here are some screenshots of the final result:

The home page.

The calendar page.

The schedule event page.

The event types admin page.

The create/edit event type admin page.

The scheduled events admin page.

In the next part of the series, we will jump into the action by creating a new Phoenix project and generating the necessary Ecto schemas for modeling both event types and events. In the meantime, you can check the end result here, or have a look at the source code.

Happy coding!

bigardone / calendlex

Simple Calendly clone with Phoenix LiveView

Three real-world examples of distributed Elixir (pt. 4)

Ricardo García Vega — Mon, 28 Jun 2021 04:38:32 +0000

In the previous part of the series, we built a distributed download request manager and tracker, taking advantage of Elixir's distributed capabilities. In this fourth and last part, we will implement a real-world example which consists of a widespread pattern in which a web service serves a JavaScript single-page application. One of the issues that can occur in this type of scenario is that we have users that keep the browser open for long sessions, in which there can be multiple deployments of the service. If any of the versions that we deploy contain breaking changes between the front-end and the back-end, they will most likely experience unexpected errors due to outdated UI versions. A good example would be changing some business logic behind a form submission that depends on a new field, which is not currently being sent because the outdated UI is not rendering, even though the backend is expecting it. This scenario gets even trickier when you can have multiple instances of your application running simultaneously, and you can have multiple nodes running different versions temporarily until the cluster eventually syncs. A best practice to prevent a bad user experience consists of displaying a warning message to the user suggesting a page refresh to get the latest app version. Let's get cracking!

The base application

Source code of this example

For this particular example, we are going to build a new web application consisting of two different parts:

A standard Phoenix application that relies on libcluster to manage the node cluster and Horde to register and supervise global processes.
A JavaScript single-page application built using Elm, containing the user interface.

Let's start by scaffolding the new project:

mix phx.new version_observer --no-ecto --no-live --no-dashboard --no-gettext

After everything gets installed, let' add the necessary dependencies:

# ./mix.exs

defmodule VersionObserver.MixProject do
  use Mix.Project

    # ...


  defp deps do
    [
      # ...

      {:libcluster, "~> 3.3"},
      {:horde, "~> 0.8.3"}
    ]
  end

    # ...
end

And configure the cluster:

# ./lib/version_observer/application.ex

defmodule VersionObserver.Application do
  use Application

  def start(_type, _args) do
    children = [
      {Cluster.Supervisor, [topologies(), [name: BackgroundJob.ClusterSupervisor]]},

      # Start the Telemetry supervisor
      VersionObserverWeb.Telemetry,
      # Start the PubSub system
      {Phoenix.PubSub, name: VersionObserver.PubSub},

      # Start Horde
      VersionObserver.HordeRegistry,
      VersionObserver.HordeSupervisor,
      VersionObserver.NodeObserver,

      # Start the Endpoint (http/https)
      VersionObserverWeb.Endpoint
      # Start a worker by calling: VersionObserver.Worker.start_link(arg)
      # {VersionObserver.Worker, arg}
    ]

    opts = [strategy: :one_for_one, name: VersionObserver.Supervisor]
    Supervisor.start_link(children, opts)
  end

    # ...

  defp topologies do
    [
      background_job: [
        strategy: Cluster.Strategy.Gossip
      ]
    ]
  end
end

Just like we did in the previous part, we are going to be copy the DownloadManager.{HordeRegistry, HordeSupervisor, NodeObserver} modules from the previous example source code repository, and pasting them into out brand new project, renaming their namespace accordingly to VersionObserver.*. We have to make a subtle change in the NodeObserver module, though:

# lib/version_observer/node_observer.ex

defmodule VersionObserver.NodeObserver do
  use GenServer

  # ...

  alias Phoenix.PubSub

  @topic "node_observer"

  def topic, do: @topic

  def handle_info({:nodeup, _node, _node_type}, state) do
    # ...

    PubSub.broadcast(VersionObserver.PubSub, @topic, :nodeup)

    {:noreply, state}
  end

  def handle_info({:nodedown, _node, _node_type}, state) do
    # ...

    PubSub.broadcast(VersionObserver.PubSub, @topic, :nodedown)

    {:noreply, state}
  end
end

In this particular example, the node observer publishes :nodeup and :nodedown messages through Phonenix.PubSub, which we will use later.

Since we are going to be testing the final result locally, we need to provide a different port to each Phoenix's server instance that we start:

# ./config/dev.exs

use Mix.Config

config :version_observer, VersionObserverWeb.Endpoint,
  http: [
    port: String.to_integer(System.get_env("PORT") || "4000")
  ],
  # ...

Frontend-wise, we are going to get rid of Phoenix's default webpack set up in favor of Parcel, which is faster and does not need any additional configuration whatsoever:

# ./assets/package.json

{
  "repository": {},
  "description": " ",
  "license": "MIT",
  "scripts": {
    "watch": "parcel watch js/app.js --out-dir ../priv/static/js --public-url /js"
  },
  "dependencies": {
    "phoenix": "file:../deps/phoenix",
    "phoenix_html": "file:../deps/phoenix_html"
  },
  "devDependencies": {
    "@babel/core": "^7.14.6",
    "elm": "^0.19.1-5",
    "elm-hot": "^1.1.6",
    "node-elm-compiler": "^5.0.6",
    "parcel-bundler": "^1.12.5"
  }
}

# ./config/dev.exs

use Mix.Config

config :version_observer, VersionObserverWeb.Endpoint,
  # ...

  watchers: [
    npm: ["run", "watch", cd: Path.expand("../assets", __DIR__)]
  ]

  # ...

We will not be diving into the front-end Elm application internals. However, you can find its source code here. Nevertheless, we need to initialize it into our main JS file:

// ./assets/js/app.js

import { Elm } from '../src/Main.elm';
import socket from './socket';
import '../css/app.css';
import 'phoenix_html';


const { appVersion } = window;

const app = Elm.Main.init({ flags: { appVersion } });

The critical part is the appVersion variable that we pass as a flag to the Elm application. This appVersion holds the version value of the Phoenix instance that serves the initial HTML that renders JavaScript single-page application. In this case, we are taking it from the window object, but where do we get its value, and where do we set it?

The application version

If we take a closer look at the mix.exs file, one of the configuration options that the project/0 function returns is version:

# ./mix.exs

defmodule VersionObserver.MixProject do
  use Mix.Project

  def project do
    [
      app: :version_observer,
      version: "0.1.0",
      # ...
    ]
  end

  # ...
end

We are going to use this value to set and read the current version of the application. Setting its value is straightforward; we only need to update it and rebuild the project. How do we read it, though? Elixir has a convenient Application.spec/1 function that returns the specifications of a given application:

iex(1)> Application.spec(:version_observer)
[
  description: 'version_observer',
  id: [],
  vsn: '0.1.0',
  modules: [VersionObserver, VersionObserver.Application,
   VersionObserver.HordeRegistry, VersionObserver.HordeSupervisor,
   VersionObserver.NodeObserver, VersionObserver.Version.Monitor,
   VersionObserver.Version.Monitor.Runner,
   VersionObserver.Version.Monitor.Starter, VersionObserver.Version.Repo,
   VersionObserverWeb, VersionObserverWeb.Endpoint,
   VersionObserverWeb.ErrorHelpers, VersionObserverWeb.ErrorView,
   VersionObserverWeb.LayoutView, VersionObserverWeb.PageController,
   VersionObserverWeb.PageView, VersionObserverWeb.Router,
   VersionObserverWeb.Router.Helpers, VersionObserverWeb.Telemetry,
   VersionObserverWeb.UserSocket, VersionObserverWeb.VersionChannel],
  maxP: :infinity,
  maxT: :infinity,
  registered: [],
  included_applications: [],
  optional_applications: [],
  applications: [:kernel, :stdlib, :elixir, :logger, :runtime_tools, :phoenix,
   :phoenix_html, :phoenix_live_reload, :telemetry_metrics, :telemetry_poller,
   :jason, :plug_cowboy, :libcluster, :horde],
  mod: {VersionObserver.Application, []},
  start_phases: :undefined
]

The option that we are looking for is :vsn, which we can get directly using Application.spec(:version_observer, :vsn).

iex(1)> Application.spec(:version_observer, :vsn)
'0.1.0'

Let's implement a module that represents the version of our application:

# ./lib/version_observer/version.ex

defmodule VersionObserver.Version do
  alias __MODULE__

  @type t :: %Version{
          major: non_neg_integer,
          minor: non_neg_integer,
          patch: non_neg_integer
        }

  defstruct major: 0, minor: 0, patch: 0

  def from_string(value) do
    with [major, minor, patch] <- to_chunks(value) do
      {:ok, %Version{major: major, minor: minor, patch: patch}}
    end
  end

  def incompatible?(%Version{major: major_1}, %Version{major: major_2}), do: major_1 != major_2

  defp to_chunks(value) do
    case String.split(value, ".") do
      [_major, _minor, _patch] = chunks ->
        Enum.map(chunks, &String.to_integer/1)

      _ ->
        {:error, :invalid_version}
    end
  rescue
    _ ->
      {:error, :invalid_version}
  end

  defimpl String.Chars do
    def to_string(%Version{major: major, minor: minor, patch: patch}) do
      "#{major}.#{minor}.#{patch}"
    end
  end
end

This module consists of a Version struct based on the semantic versioning specification and two helper functions:

from_string: builds a new struct from a string.
incompatible?: it takes two versions and returns whether both are incompatible or not.

It also implements the String.Chars protocol, to convert a version into a string. For the sake of simplicity, the logic of this module is very simple, however, you can adapt it to your personal needs, especially the incompatible? implementation. To continue, let's add a new repository module in charge of storing the application version:

# ./lib/version_observer/version/repo.ex

defmodule VersionObserver.Version.Repo do
  use GenServer

  alias VersionObserver.Version

  def start_link(opts) do
    name = Keyword.get(opts, :name, __MODULE__)

    GenServer.start_link(__MODULE__, %{}, name: name)
  end

  def get(name \\ __MODULE__), do: GenServer.call(name, :get)

  @impl true
  def init(_) do
    {:ok, version} =
      :version_observer
      |> Application.spec(:vsn)
      |> to_string()
      |> Version.from_string()

    {:ok, version}
  end

  @impl GenServer
  def handle_call(:get, _, version) do
    {:reply, {:ok, version}, version}
  end
end

The VersionObserver.Version.Rep module is a basic GenServer implementation that takes the :vsn value from the application, builds a new %Version{} with it, and stores it in its state. It also exposes a get/0 function that returns the stored version struct. Finally, we have to add the repo to the main application's children specification:

# ./lib/version_observer/application.ex

defmodule VersionObserver.Application do
  use Application

  def start(_type, _args) do
    children = [
      # ...

      VersionObserver.Version.Repo,

      # ...
    ]
  end

  # ...
end

And expose a convenient function in the main VersionObserver module:

# ./lib/version_observer.ex

defmodule VersionObserver do
  defdelegate get_current_version, to: VersionObserver.Version.Repo, as: :get
end

Jumping to IEX and requesting the version should return the following:

Interactive Elixir (1.12.1) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> VersionObserver.get_current_version()
{:ok, %VersionObserver.Version{major: 0, minor: 1, patch: 0}}

It works like a charm. Let's update the main layout view and template to set the current value in the window object:

# ./lib/version_observer_web/templates/layout/app.html.eex

<!DOCTYPE html>
<html lang="en">
  <head>
    <%# ... %>

    <script>window.appVersion = '<%= get_current_version() %>';</script>
  </head>
  <body>
    <%= @inner_content %>
  </body>
</html>

# ./lib/version_observer_web/views/layout_view.ex

defmodule VersionObserverWeb.LayoutView do
  use VersionObserverWeb, :view

  def get_current_version do
    {:ok, version} = VersionObserver.get_current_version()

    to_string(version)
  end
end

If we now start the Phoenix server and visit http://localhost:4000, we should see the single-page application getting rendered correctly:

At this point, we have or base application ready. When a user visits the home page, the main layout renders, setting the current version of the application and starting the JS app, passing the version as a flag. However, if we deploy a different version number, the user will still be running the app's initial version unless there is a page refresh. How can we alert the user about this?

Monitoring version changes in a cluster of nodes

If we start different nodes, they will be running their own NodeObserver.Version.Repo that stores their application version. We need a new process, unique across all nodes, that listens to topology changes in the cluster, broadcasting any version changes when they occur. Following the same approach that we did in the second part, let's implement a singleton process to take care of this task:

# ./lib/version_observer/version/monitor.ex

defmodule VersionObserver.Version.Monitor do
  use GenServer

  alias __MODULE__.Runner
  alias Phoenix.PubSub
  alias VersionObserver.{NodeObserver, Version}

  @publish_opic "version_monitor"

  def start_link(opts) do
    name = Keyword.get(opts, :name, __MODULE__)
    subscribe_topic = Keyword.get(opts, :subscribe_topic, NodeObserver.topic())

    GenServer.start_link(__MODULE__, subscribe_topic, name: name)
  end

  def init(subscribe_topic) do
    PubSub.subscribe(VersionObserver.PubSub, subscribe_topic)

    {:ok, %Version{}}
  end

  def handle_info(:nodeup, state) do
    {:noreply, state, {:continue, :check}}
  end

  def handle_info(:nodedown, state) do
    {:noreply, state, {:continue, :check}}
  end

  def handle_continue(:check, state) do
    with {:ok, new_version} <- Runner.run(),
         true <- Version.incompatible?(new_version, state) do
      Process.sleep(1_000)

      PubSub.broadcast(
        VersionObserver.PubSub,
        @publish_topic,
        {:new_version, to_string(new_version)}
      )

      {:noreply, new_version}
    else
      false ->
        {:noreply, state}

      {:error, :invalid_nodes} ->
        Process.sleep(1_000)

        {:noreply, state, {:continue, :check}}

      {:error, :out_of_sync} ->
        {:noreply, state}
    end
  end
end

The VersionObserver.Version.Monitor is another straightforward GenServer implementation, which takes its name and subscribe_topic from the start_link/1 function options. On its init/1 function, it takes the subscribe_topic to subscribe to the Phoenix.PubSub node observer topic, that we will see in a moment, and sets an empty %Version{} as its state. Subscribing to this topic involves that the monitor process will receive incoming messages whenever nodes join or leave the cluster, so we need to implement this message handling with their corresponding handle_info(:nodeup, state) and handle_info(:nodedown, state) callbacks, which return a {:continue, :check} tuple handled by handle_continue(:check, state), which:

It calls its Runner.run/0 module function, which we will see now, which checks if all nodes run the same application version.
It checks if the returned version is incompatible with the current one stored in its state, publishing the new version through Phoenix.Pubsub if so.
On the other hand, if they are compatible, everything is fine, and it does nothing.
If the runner module returns {:error, :invalid_nodes}, it means that the new nodes are still starting, and it sleeps for a second and retries the whole process again by returning {:continue, :check}.
Finally, if the return value is {:error, :out_of_sync}, it means that there are nodes currently running different versions of the application, probably due to an ongoing deployment, so we need to wait until it finishes and the cluster recovers.

Let's add the runner module:

# ./lib/version_observer/version/monitor/runner.ex

defmodule VersionObserver.Version.Monitor.Runner do
  alias VersionObserver.Version.Repo

  def run do
    case GenServer.multi_call(Repo, :get) do
      {nodes, []} ->
        do_check(nodes)

      {_, invalid_nodes} ->
        {:error, :invalid_nodes}
    end
  end

  defp do_check(nodes) do
    nodes
    |> Keyword.values()
    |> Enum.uniq()
    |> case do
      [{:ok, version}] ->
        {:ok, version}

      other ->
        {:error, :out_of_sync}
    end
  end
end

The run/0 function runs GenServer.multi_call/4, which calls all the NodeObserver.Version.Repo process in the cluster. The result is a tuple containing two elements:

The first one is the list of replies in the form of [node, result].
The second, a list of invalid nodes or nodes that didn't reply.

If there are invalid nodes, it returns a {:error, :invalid_nodes} tuple. On the other hand, if all nodes have replied correctly, it takes all the unique versions and checks if there is only one, which means that all nodes are running the same one, returning {:ok, version} or {:error, :out_of_sync} if the contrary. The last thing we have to implement is the process that starts and registers the singleton NodeObserver.Version.Monitor globally across the cluster:

# ./lib/version_observer/version/monitor/starter.ex

defmodule VersionObserver.Version.Monitor.Starter do
  require Logger

  alias VersionObserver.{
    HordeRegistry,
    HordeSupervisor,
    Version.Monitor
  }

  # ...

  def start_link(opts) do
    name =
      opts
      |> Keyword.get(:name, Monitor)
      |> via_tuple()

    opts = Keyword.put(opts, :name, name)

    child_spec = %{
      id: Monitor,
      start: {Monitor, :start_link, [opts]}
    }

    HordeSupervisor.start_child(child_spec)

    :ignore
  end

  defp via_tuple(name) do
    {:via, Horde.Registry, {HordeRegistry, name}}
  end
end

# ./lib/version_observer/application.ex

defmodule VersionObserver.Application do
  use Application

  def start(_type, _args) do
    children = [
      # ...
      VersionObserver.Version.Monitor.Starter,

      # ...
    ]

    opts = [strategy: :one_for_one, name: VersionObserver.Supervisor]
    Supervisor.start_link(children, opts)
  end

    # ...
end

Alerting the user about new available application versions

The only thing left is to subscribe to the NodeObserver.Version.Monitor messages and show the corresponding alert to the user. To achieve this, let's add a new Phoenix channel module:

# ./lib/version_observer_web/channels/user_socket.ex

defmodule VersionObserverWeb.UserSocket do
  use Phoenix.Socket

  channel("version", VersionObserverWeb.VersionChannel)

  # ...
end

# ./lib/version_observer_web/channels/version_channel.ex

defmodule VersionObserverWeb.VersionChannel do
  use VersionObserverWeb, :channel

  alias Phoenix.PubSub

  def join("version", _payload, socket) do
    PubSub.subscribe(VersionObserver.PubSub, "version_monitor")

    {:ok, socket}
  end

  def handle_info({:new_version, version}, socket) do
    push(socket, "new_version", %{version: version})

    {:noreply, socket}
  end
end

When the client joins the channel, its process subscribes to the version monitor topic, pushing any new version through the socket. We also need to change the app.js logic to pass the new version to the JavaScript single-page application:

// ./assets/js/app.js

// ...

const channel = socket.channel('version', {});

channel.join()
  .receive('ok', (resp) => {
    channel.on('new_version', ({ newVersion }) => {
      app.ports.newVersion.send(newVersion);
    });
  });

Finally, the logic inside the Elm, React, or whatever front-end technology you choose should be straightforward. It compares the version it received via its initialization flags to the one received from the Phoenix socket client, displaying the corresponding message suggesting to refresh the page. Let's jump back to the terminal, start the load balancer like in the previous part, and start a a couple of instances of our application, and try to simulate some deployments:

n1 starts, and as soon as n2 joins the cluster, the VersionObserver.Version.Monitor receives a :nodeup message from the VersionObserver.NodeObserver, requesting the application version to all the nodes. However, n2 is not yet ready, so it receives the invalid nodes error, making the monitor retry again after a second. In the second attempt, n2 is ready, and both nodes have the same version, so nothing else happens. Let's kill all the instances and start a single one, and visit http://localhost:

Next, let's update the mix.exs file, setting the version value to a new major value, and start n2 and n3:

# ./mix.exs

defmodule VersionObserver.MixProject do
  use Mix.Project

  def project do
    [
      app: :version_observer,
      version: "1.0.0",
      # ...
    ]
  end

  # ...
end

n2 and n3 start, and the version monitor running on n1 starts checking for the version on each node, ending up receiving two different: version 0.1.0 running in n1 and 1.0.0 running in both n2 and n3. Let's kill n1, leaving the cluster with nodes that have the same version:

If we check the browser, we should see the corresponding message popping up:

Yay!

Conclusion

In this series, we have seen how to build a cluster of Elixir nodes and take advantage of its distribution capabilities to implement three different creative solutions to real-world problems, otherwise impossible without adding external dependencies and complexity to our projects. This power and flexibility make me like Elixir so much and enjoy writing back-end code every day. I hope you enjoyed the posts as much as I did writing them, and if you have any examples about distributed Elixir solutions, please share them with me, I'd love to hear from you 🙌.

Happy coding!

bigardone / distributed-elixir-examples

Code examples for the "Three real-world examples of distributed Elixir" blog series

Three real-world examples of distributed Elixir (pt. 3)

Ricardo García Vega — Fri, 18 Jun 2021 08:14:12 +0000

In the last part of the series, we saw how to create a singleton process across a cluster of nodes, using three different global registries. This approach is commonly used to run a unique background task that you want to keep running no matter what changes happen in the cluster's topology. However, we can use a similar pattern to run short-time running tasks that will die once they finish their job, with the same guarantees. An excellent example of this would be an application where users can download a file. However, generating the file is an expensive task that can take some seconds, and you want to notify the user of the progress. Eventually, when the file is ready, the application should provide the user with the download URL. Of course, all these should happen if the node where the download task is running shuts down, the user refreshes the page connecting to a different instance, etc. Let's get cracking!

The base application

Source code of this example

For today's example, we will create a web application on top of:

libcluster for building the cluster of nodes.
Horde to handle both the process registry and supervision, as we saw in the previous part of the series.
Phoenix, Elixir's web framework, designed and built from the ground up to take advantage of Elixir's distribution features.
Phoenix.LiveView for the front-end to give real-time updates to the user.

Let's start by generating a new project from the terminal:

mix phx.new download_manager --no-ecto --live --no-dashboard --no-gettext

Next, let's add the initial dependencies that we need and configure the cluster definition:

# ./mix.exs

defmodule DownloadManager.MixProject do
  use Mix.Project
  # ...

  defp deps do
    [
      # ...

      {:libcluster, "~> 3.3"},
      {:horde, "~> 0.8.3"},
    ]
  end

  # ...
end

# .lib/download_manager/application.ex

defmodule DownloadManager.Application do
  use Application

  def start(_type, _args) do
    children = [
      {Cluster.Supervisor, [topologies(), [name: BackgroundJob.ClusterSupervisor]]},
      # Start the Telemetry supervisor
      DownloadManagerWeb.Telemetry,
      # Start the PubSub system
      {Phoenix.PubSub, name: DownloadManager.PubSub},
      DownloadManager.HordeRegistry,
      DownloadManager.HordeSupervisor,
      DownloadManager.NodeObserver,

      # Start the Endpoint (http/https)
      DownloadManagerWeb.Endpoint
    ]

    opts = [strategy: :one_for_one, name: DownloadManager.Supervisor]
    Supervisor.start_link(children, opts)
  end

  def config_change(changed, _new, removed) do
    DownloadManagerWeb.Endpoint.config_change(changed, removed)
    :ok
  end

  defp topologies do
    [
      background_job: [
        strategy: Cluster.Strategy.Gossip
      ]
    ]
  end
end

We are not going to dive into the details of the DownloadManager.HordeRegistry, DownloadManager.HordeSupervisor, and DownloadManager.NodeObserver, since we already did in the last part. Still, they are the modules needed to make Horde work appropriately in a cluster of dynamic nodes, so we will just copy them and rename their namespace to match the current DownloadManager. Since we will start multiple nodes and Phoenix runs in port 4000 by default, we will have issues due to the port already taken by the first instance that we start. Let's change the development configuration so that it takes the port number from the environment:

# ./config/dev.exs

use Mix.Config

config :download_manager, DownloadManagerWeb.Endpoint,
  http: [
    port: String.to_integer(System.get_env("PORT") || "4000")
  ],
  # ...

Last but not least, let's get rid of all the predefined Phoenix styles and, to create a simple yet beautiful UI, let's add the Tailwind CSS CDN stylesheet link:

# ./lib/download_manager_web/templates/layout/root.html.leex

<!DOCTYPE html>
<html lang="en">
  <head>
    # ...

    <link href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css" rel="stylesheet">

    # ...
  </head>
  <body>
    <%= @inner_content %>
  </body>
</html>

We are not going to do an in-depth exploration of the styles either. However, you can find all the files in the example repository, and this is how the final result looks like:

The downlad struct and repository

With the basic project structure ready, let's start working on the download request logic. First of all, let's define what a download request looks like:

# ./lib/download_manager/download.ex

defmodule DownloadManager.Download do
  alias __MODULE__
  alias DownloadManager.Token

  @pending_state :pending
  @processing_state :processing
  @error_state :error
  @ready_state :ready

  @enforce_keys [:id, :state, :user_id]

  defstruct [
    :file_url,
    :id,
    :state,
    :user_id
  ]

  def new(params) do
    with {:ok, user_id} <- Keyword.fetch(params, :user_id) do
      %Download{
        id: Token.generate(),
        state: @pending_state,
        user_id: user_id
      }
    end
  end
end

The DownloadManager.Download struct holds the following data:

id: the unique internal ID of the download.
state: the current state of the download, which can be any of :pending, :processing, :error, or :ready.
file_url: the downloadable file's URL.
user_id: the ID of the user who requested the download.

We are also adding a convenient new/1 helper function to build download structs, which by default sets an randomly generated :id value along with the :pending state. In a real-life application, we would temporarily store download requests in some sort of in-memory data storage like the good old Redis. However, we will stick to our no-external-dependencies approach and define a new module that serves as the download request repository:

# ./lib/download_manager/download/repo.ex

defmodule DownloadManager.Download.Repo do
  alias DownloadManager.Download

  @adapter Application.compile_env(:download_manager, __MODULE__)[:adapter]

  @type user_id :: String.t()
  @type result :: {:ok, Download.t()} | {:error, term}

  @callback start(keyword) :: GenServer.on_start()
  @callback fetch(user_id()) :: result
  @callback insert(Download.t()) :: result
  @callback update(Download.t()) :: result
  @callback remove(Download.t()) :: result

  defdelegate start_link(opts), to: @adapter
  defdelegate fetch(user_id), to: @adapter
  defdelegate insert(download), to: @adapter
  defdelegate update(download), to: @adapter
  defdelegate remove(download), to: @adapter

  def child_spec(opts) do
    %{
      id: __MODULE__,
      start: {__MODULE__, :start_link, [opts]},
      type: :worker,
      restart: :permanent,
      shutdown: 500
    }
  end
end

This module defines five different behavior callbacks:

start/1: which starts the current adapter.
fetch/1: which searches the current download for a given user_id.
insert/1: which inserts the given download.
update/1: which updates the given download.
remove/1: which deletes the given download.

Using dependency injection to set the @adapter module variable, it delegates all the public functions to the configured adapter. This technique is very convenient when you want to have different adapters for different environments, especially when the production adapter points to an external service, but you want your tests to use a mock implementation to avoid any external dependencies. For the sake simplicity, we will use nebulex, which is a distributed in-memory cache library, so let's add it to the application dependencies:

# ./mix.exs

defmodule DownloadManager.MixProject do
  use Mix.Project

  # ...

  defp deps do
    [
      # ...

      # Additional deps
      # ...
      {:nebulex, "~> 2.1"}
    ]
  end

  # ...
end

Next, we can implement a DownloadManager.Download.Repo adapter module following nebulex's documentation:

# .lib/download_manager/download/repo/nebulex.ex

defmodule DownloadManager.Download.Repo.Nebulex do
  use Nebulex.Cache,
    otp_app: :download_manager,
    adapter: Nebulex.Adapters.Replicated

  alias DownloadManager.{Download, Download.Repo}

  @behaviour Repo

  @impl Repo
  def start(opts) do
    start_link(opts)
  end

  @impl Repo
  def fetch(user_id) do
    case get(user_id) do
      nil ->
        {:error, :not_found}

      download ->
        {:ok, download}
    end
  end

  @impl Repo
  def insert(%Download{user_id: user_id} = download) do
    if put_new(user_id, download) do
      {:ok, download}
    else
      {:error, :unexpected_error}
    end
  end

  @impl Repo
  def update(%Download{user_id: user_id} = download) do
    :ok = put(user_id, download, ttl: :timer.seconds(5))

    {:ok, download}
  end

  @impl Repo
  def remove(%Download{user_id: user_id} = download) do
    :ok = delete(user_id)

    {:ok, download}
  end
end

The module implements the DownloadManager.Download.Repo behavior by calling the specific Nebulex functions in its callbacks, thanks to Nebulex's convenient API. Finally, we have to configure the repository's adapter in the application's configuration, and add the repository module to the main application supervision tree:

# ./config/config.exs

use Mix.Config

# ...

config :download_manager, DownloadManager.Download.Repo,
  adapter: DownloadManager.Download.Repo.Nebulex

# ...

# .lib/download_manager/application.ex

defmodule DownloadManager.Application do
  use Application

  def start(_type, _args) do
    children = [
      # ...
      DownloadManager.Download.Repo,
      # ...
    ]

    opts = [strategy: :one_for_one, name: DownloadManager.Supervisor]
    Supervisor.start_link(children, opts)
  end

  # ...
end

Let's jump to the interactive shell and test out the repository:

➜ iex --sname n1 -S mix
# ...

iex(n1@mbp)1> [user_id: "user-1"] |> DownloadManager.Download.new() |> DownloadManager.Download.Repo.insert()
{:ok,
 %DownloadManager.Download{
   file_url: nil,
   id: "sOB4hY6ylz",
   state: :pending,
   user_id: "user-1"
 }}

If we start a different node and try to get the download for user-1, we should be able to see it:

➜ iex --sname n2 -S mix
# ...

iex(n2@mbp)1> DownloadManager.Download.Repo.fetch("user-1")
{:ok,
 %DownloadManager.Download{
   file_url: nil,
   id: "XLaXS2YeOO",
   state: :pending,
   user_id: "user-1"
 }}

Creating and tracking downloads

With the download definition and the distributed repository working, we can move on to the next thing: requesting a download and tracking its progress. First, let's implement the module which starts new download request processes:

# ./lib/download_manager/download/tracker.ex

defmodule DownloadManager.Download.Tracker do
  alias __MODULE__.Worker
  alias DownloadManager.{Download, Download.Repo, HordeRegistry, HordeSupervisor}

  @spec start(String.t()) :: {:ok, Download.t()} | {:error, term}
  def start(user_id) do
    with download <- Download.new(user_id: user_id),
         {:ok, download} <- Repo.insert(download),
         child_spec <- worker_spec(download),
         {:ok, _} <- HordeSupervisor.start_child(child_spec) do
      {:ok, download}
    end
  end

  defp worker_spec(%Download{user_id: user_id} = download) do
    %{
      id: {Worker, user_id},
      start: {Worker, :start_link, [[download: download, name: via_tuple(user_id)]]},
      type: :worker,
      restart: :transient
    }
  end

  defp via_tuple(id) do
    {:via, Horde.Registry, {HordeRegistry, {Download, id}}}
  end
end

The Tracker module exposes a public start function that expects a user_id. Using this ID generates a new download, inserts it into the repository, generates a worker child spec, and finally starts the tracker worker process using the Horde supervisor, returning the created download. Please notice the {:via, Horde.Registry, {HordeRegistry, {Download, id}}} name option it sets in the worker spec to register the process globally across all nodes. The worker's responsibility is simple: to keep track of the download file generation reporting the progress. Nevertheless, depending on your particular case, generating downloadable files can imply different things, from processing significant amounts of data locally to relying on an external service, having to handle the communication between both applications. Therefore, let's follow the same dependency injection approach that we took in the download repository and create a worker behavior module:

# ./lib/download_manager/download/tracker/worker.ex

defmodule DownloadManager.Download.Tracker.Worker do
  @adapter Application.compile_env(:download_manager, __MODULE__)[:adapter]

  @callback start_link(keyword) :: GenServer.on_start()

  defdelegate start_link(opts), to: @adapter
end

Again, for the sake of simplicity, we are going to build a fake worker implementation that gives us enough time to mess around in the interactive shell:

# ./lib/download_manager/download/tracker/worker/fake.ex

defmodule DownloadManager.Download.Tracker.Worker.Fake do
  use GenServer

  alias DownloadManager.{Download, Download.Repo}
  alias Phoenix.PubSub

  def start_link(opts) do
    name = Keyword.get(opts, :name, __MODULE__)
    download = Keyword.fetch!(opts, :download)

    GenServer.start_link(__MODULE__, download, name: name)
  end

  @impl GenServer
  def init(download) do
    schedule(:start, 1_000)

    {:ok, download}
  end

  @impl GenServer
  def handle_info(:start, download) do
    {:ok, new_download} =
      download
      |> Download.with_pending_state()
      |> Repo.update()

    broadcast(new_download)
    schedule(:process, 1_000)

    {:noreply, new_download}
  end

  def handle_info(:process, download) do
    {:ok, new_download} =
      download
      |> Download.with_processing_state()
      |> Repo.update()

    broadcast(new_download)
    schedule(:ready, 5_000)

    {:noreply, new_download}
  end

  def handle_info(:ready, %Download{id: id, user_id: user_id} = download) do
    {:ok, new_download} =
      download
      |> Download.with_ready_state()
      |> Download.with_file_url("/downloads/#{id}.pdf")
      |> Repo.update()

    broadcast(new_download)

    {:stop, :normal, new_download}
  end

  defp schedule(action, timeout) do
    Process.send_after(self(), action, timeout)
  end

  defp broadcast(%Download{user_id: user_id} = download) do
    PubSub.broadcast(DownloadManager.PubSub, "download:#{user_id}", {:update, download})
  end
end

The module is a straightforward GenServer implementation, which takes a name and a download in its options, being download its internal state. It then starts a loop of scheduled internal messages, in which updates its download with the next state, updating the download stored in the repo and broadcasting the new download through Phoenix.PubSub using the download:#{user_id} topic. Eventually, when the download is ready, it sets a fake download URL and exits normally. Let's jump into iex and test it out:

➜ iex -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

[info] Starting Horde.RegistryImpl with name DownloadManager.HordeRegistry
[info] Starting Horde.DynamicSupervisorImpl with name DownloadManager.HordeSupervisor
Interactive Elixir (1.12.1) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> download = [user_id: "user-1"] |> DownloadManager.Download.new()
%DownloadManager.Download{
  file_url: nil,
  id: "QOotjQuQSP",
  state: :pending,
  user_id: "user-1"
}
iex(2)> DownloadManager.Download.Tracker.Worker.start_link(download: download)
{:ok, #PID<0.379.0>}
iex(3)> [info] ----[nonode@nohost-#PID<0.379.0>] Elixir.DownloadManager.Download.Tracker.Worker.Fake starting download: %DownloadManager.Download{file_url: nil, id: "QOotjQuQSP", state: :pending, user_id: "user-1"}
[info] ----[nonode@nohost-#PID<0.379.0>] Elixir.DownloadManager.Download.Tracker.Worker.Fake processing download: %DownloadManager.Download{file_url: nil, id: "QOotjQuQSP", state: :pending, user_id: "user-1"}
[info] ----[nonode@nohost-#PID<0.379.0>] Elixir.DownloadManager.Download.Tracker.Worker.Fake download ready: %DownloadManager.Download{file_url: "/downloads/QOotjQuQSP.pdf", id: "QOotjQuQSP", state: :ready, user_id: "user-1"}

It is working as expected, excellent. We can't forget about configuring the tracker's worker adapter though:

# ./config/config.exs

use Mix.Config

# ...

config :download_manager, DownloadManager.Download.Tracker.Worker,
  adapter: DownloadManager.Download.Tracker.Worker.Fake

# ...

And this is pretty much it in terms of the back-end logic. Therefore, let's move forward to the front-end and implement the interaction with the user.

Requesting downloads from the UI

User experience-wise, we want to focus on three requirements primarily:

A user can only request a download at a time.
If the user refreshes the browser while a download is in progress, the user shouldn't lose track of the current download once the page loads again.
The previous point also applies when the instance to which the user connected goes down.

Having this in mind, let's start by creating a Plug to identify users uniquely, fulfilling the first point:

# ./lib/download_manager_web/plug/auth_plug.ex

defmodule DownloadManagerWeb.AuthPlug do
  @behaviour Plug

  alias DownloadManager.Token
  alias Plug.Conn

  @impl Plug
  def init(opts), do: opts

  @impl Plug
  def call(conn, _opts) do
    case Conn.get_session(conn) do
      %{"user_id" => _} ->
        conn

      _ ->
        Conn.put_session(conn, :user_id, Token.generate())
    end
  end
end

This plug fakes an authentication mechanism, checking if there is already a user_id in the session, setting a new random one if it does not. This user_id gets stored in a browser cookie, hence every time we visit the application we will use the same user_id. Let's add the plug into the router:

# ./lib/download_manager_web/router.ex

defmodule DownloadManagerWeb.Router do
  use DownloadManagerWeb, :router

  pipeline :browser do
    # ...
    plug DownloadManagerWeb.AuthPlug
  end

  # ...
end

Having the user_id ready in the session, we can edit the live page module, which is the main and only entry point to our application:

# ../lib/download_manager_web/live/page_live.ex

defmodule DownloadManagerWeb.PageLive do
  use DownloadManagerWeb, :live_view

  alias Phoenix.PubSub

  @impl Phoenix.LiveView
  def mount(_params, %{"user_id" => user_id}, socket) do
    PubSub.subscribe(DownloadManager.PubSub, "download:#{user_id}")

    download =
      case DownloadManager.fetch_download(user_id) do
        {:ok, download} ->
          download

        {:error, :not_found} ->
          nil
      end

    {:ok, assign(socket, user_id: user_id, download: download)}
  end

  # ...
end

In the mount/3 callback, it takes the user_id from the session and immediately subscribes to the down_load:#{user_id} topic. Next, it checks if the user already has a download in progress, assigning it to the socket (or nil if there is no download). Notice that we are using DownloadManager.fetch_download/1 to fetch the download. I like adding all the functions the DownloadManagerWeb.* namespace needs from DownloadManager.* in the main DownloadManager module, acting as a public contract between them, so that the web modules don't need to know any implementation details of the business modules. Let's add the functions that we need really quick:

# ./lib/download_manager.ex

defmodule DownloadManager do
  defdelegate start_download(user_id), to: DownloadManager.Download.Tracker, as: :start

  defdelegate fetch_download(user_id), to: DownloadManager.Download.Repo, as: :fetch

  defdelegate delete_download(download), to: DownloadManager.Download.Repo, as: :remove
end

As you can see, it exposes three different functions that delegate to the proper business modules. We can now edit the live view template to add the button which triggers the download request:

# ./lib/download_manager_web/live/page_live.html.leex

<section class="px-6">
  # ...

  <div class="my-6 flex items-center gap-x-4">
    # ...

    <%= if is_nil(@download) do %>
      <button phx-click="request_download" class="rounded text-purple-200 text-sm bg-purple-900 ml-auto h-8 px-6 flex items-center">Download PDF</button>
    <% end %>
  </div>

  # ...
</section

If there is no download set in the socket assigns, it renders the button which triggers a request_download event on its click event. Let' implement the corresponding callback in the live page module:

# ../lib/download_manager_web/live/page_live.ex

defmodule DownloadManagerWeb.PageLive do
  use DownloadManagerWeb, :live_view

  # ...

  @impl Phoenix.LiveView
  def handle_event("request_download", _, socket) do
    case DownloadManager.start_download(socket.assigns.user_id) do
      {:ok, download} ->
        {:noreply, assign(socket, download: download)}

      _ ->
        {:noreply, put_flash(socket, :error, "Error creating download request")}
    end
  end

  # ...
end

The function starts by calling the DownloadManager.start_download/1 function which we have previously delegated to DownloadManager.Download.Tracker.start/1, using the current user_id. If the call goes fine, it assigns the resulting download to the socket, setting a flash error if the contrary. By assigning the download, we can show its progress to the user by adding a live component to the page template:

# ./lib/download_manager_web/live/page_live.html.leex

# ...

<%= if @download != nil do %>
  <%= live_component DownloadManagerWeb.DownloadLiveComponent, download: @download %>
<% end %>

# ./lib/download_manager_web/live/components/download_component.ex

defmodule DownloadManagerWeb.DownloadLiveComponent do
  use Phoenix.LiveComponent

  alias DownloadManager.Download

  @pending_state Download.pending_state()
  @processing_state Download.processing_state()
  @ready_state Download.ready_state()

  def render(%{download: %Download{state: state}} = assigns) do
    ~L"""
    <div>
      <div class="bg-white p-5 rounded shadow-md absolute top-0 right-0 w-80 mt-6 mr-6 border-gray-100 border text-sm leading-7 flex gap-x-4">
        <%= icon(state) %>
        <div>
          <h4 class="font-bold">Generating downloadable file</h4>
          <p class="text-gray-500"><%= state_text(state) %></p>
          <%= if Download.ready?(@download) do %>
            <a phx-click="delete_download" class="text-purple-800 cursor-pointer hover:underline" hrerf="<%= @download.file_url %>">Click me to download the file</a>
          <% end %>
        </div>
      </div>
    </div>
    """
  end

  defp state_text(@pending_state), do: "Starting download request"
  defp state_text(@processing_state), do: "Generating file..."
  defp state_text(@ready_state), do: "File generated with success"

  defp icon(@ready_state) do
    # icon content
  end

  defp icon(_) do
    # icon content
  end
end

The download component is pretty straightforward. It renders a popup, changing its content depending on the current state of the assigned download. However, we haven't yet handled any download progress updates in live view, so let's fix this:

# ../lib/download_manager_web/live/page_live.ex

defmodule DownloadManagerWeb.PageLive do
  use DownloadManagerWeb, :live_view

  # ...

  @impl Phoenix.LiveView
  def handle_info({:update, download}, socket) do
    {:noreply, assign(socket, download: download)}
  end
end

By doing this, every time the DownloadManager.Download.Tracker.Worker.Fake module broadcasts a download update, the updated download is assigned to the socket, forcing a new render of the component. The last thing we need to implement is the delete_download event triggered from the download component when the user clicks the file URL:

# ../lib/download_manager_web/live/page_live.ex

defmodule DownloadManagerWeb.PageLive do
  use DownloadManagerWeb, :live_view

  # ...

  def handle_event("delete_download", _, socket) do
    download = socket.assigns.download

    DownloadManager.delete_download(download)

    {:noreply, assign(socket, download: nil)}
  end

  # ...
end

The callback function deletes the current user download from the repository. It also sets the assigned download to nil, conveniently rendering the button again to let the user start a new download request without refreshing the browser.

Testing the application locally

Now that we have finished implementing the solution let's do some local testing. The tricky part of running different simultaneous instances, and let Phoenix do its magic regarding process communication and socket connections, is that:

We need to run each instance on a different port number.
We need a single entry point for all the possible nodes.

The first point is straightforward as we have already configured the application to accept a PORT number from the environment. We can start different instances running PORT=4001 elixir --sname n1 -S mix phx.server, using different ports and node names. On the other hand, the second point requires a bit more work, as we need to set up a load balancer. A simple way of doing this is using NGINX with a configuration similar to the following:

# /usr/local/etc/nginx/sites-available/default.conf

upstream loadbalancer {
  server 127.0.0.1:4001 weight=1;
  server 127.0.0.1:4002 weight=1;
  server 127.0.0.1:4003 weight=1;
}

resolver 127.0.0.11;

server {
  location / {
    proxy_pass http://loadbalancer;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
  }
}

Once we have the load balancer up and running, let's start three different nodes on three different terminal windows/panes:

If we jump to the browser and visit http://localhost, we should see our live page. Let's click the download button and see what happens:

The download message pops up, and we can see the different progress messages until the download is finally ready. Let's inspect the terminal to see what happens under the hood:

n2 receives the browser connection request, serving the live page. When we clicked the download button, this request started in n2, but the download process spawned in n3 due to Horde's internals. Once the download is ready, thanks to Elixir's distribution model and Phoenix's PubSub, n2 receives the corresponding message, passing the result back to the user through the socket. Let's start and new download request, and shut down the node where the download process runs:

This time, both the socket connection and the download process start in n2. Shutting down n2 causes the following:

The live page reconnects to n1.
The download process dies, but thanks to Horde it continues back in n3.
n1 receives the corresponding message from n3 once the download is ready.

And all of this is totally transparent to the user. Isn't it amazing?

Conclusion

In this example, we have taken advantage of Elixir's distributed capabilities to build a practical solution around cross-node process messaging, in-memory storage, and dynamic global supervision. The implementation has been very straightforward and without the need for any external dependency, such as job queues or third-party in-memory storage. In the next part, we will implement the last example of the series: a distributed mechanism that monitors the deployed version of the application in each node, sending a message to the front-end suggesting the user to refresh the browser if a new version gets deployed. In the meantime, don't forget to take a look at the source code of this example.

Happy coding!

bigardone / distributed-elixir-examples

Code examples for the "Three real-world examples of distributed Elixir" blog series

Three real-world examples of distributed Elixir (pt. 2)

Ricardo García Vega — Sun, 06 Jun 2021 06:09:15 +0000

In the last part of the series, we saw how to manually build a cluster of nodes in an Elixir application, ending up automating the process using libcluster. In this part, we will implement the first of our three real-world examples: a singleton process across the cluster that executes a periodic task and restarts in any node when it dies or starts in a new node when the current node where it is running goes down. Let's get cracking!

A tale of a periodic singleton process and three different global registries

The tricky part of making a process unique across the cluster is registering it using a unique name in a global registry. There are some global registries out there, being :global, swarm, and horde, probably the most popular ones. All of them have their caveats and issues, so before implementing a solution like this, you should first consider if you can deal with them, especially if you plan to store any data in the global process, in which case it is not probably the best solution. Nevertheless, our global process will only be in charge of executing a periodic task, like deleting outdated data from a database, so we should be ok if something goes wrong since it will not affect our main business logic. This said, let's start building our solution around :global and then iterate using swarm and horde alternatives.

The database cleaner process using the `:global` registry

Source code of this example

The first registry that we will use is :global, a global name registry provided by Erlang out of the box. It stores names in a table locally on every node, syncing them on any table or cluster topology change. Let's start by generating a new application:

mix new global_background_job --sup

Let's add the only dependency that we need, which is libcluster:

# ./mix.exs

defmodule GlobalBackgroundJob.MixProject do
  use Mix.Project

  # ...

  defp deps do
    [
      {:libcluster, "~> 3.3"}
    ]
  end
end

After running the corresponding mix deps.get, let's configure our cluster:

# ./lib/background_job/application.ex

defmodule GlobalBackgroundJob.Application do
  @moduledoc false

  use Application

  @impl true
  def start(_type, _args) do
    children = [
      {Cluster.Supervisor, [topologies(), [name: GlobalBackgroundJob.ClusterSupervisor]]}
    ]

    # ...
  end

  defp topologies do
    [
      background_job: [
        strategy: Cluster.Strategy.Gossip
      ]
    ]
  end

We will use the Cluster.Strategy.Gossip strategy, which auto-discovers new nodes, letting us add any number of nodes that want to the cluster without defining them statically. With the cluster configured, we can implement the server which runs the periodic task to delete outdated data from the database:

# ./lib/background_job/database_cleaner.ex

defmodule GlobalBackgroundJob.DatabaseCleaner do
  use GenServer
  require Logger

  alias __MODULE__.Runner

  @impl GenServer
  def init(args \\ []) do
    timeout = Keyword.get(args, :timeout)

    schedule(timeout)

    {:ok, timeout}
  end

  @impl GenServer
  def handle_info(:execute, timeout) do
    Task.start(Runner, :execute, [])

    schedule(timeout)

    {:noreply, timeout}
  end

  defp schedule(timeout) do
    Process.send_after(self(), :execute, timeout)
  end
end

As you can see, this is pretty much a straightforward generic server, which takes a timeout value from its init configuration, calling schedule with it and setting it as the server state. The schedule function takes the timeout value and calls Process.send_after(self(), :execute, timeout) with it. Finally, the def handle_info(:execute, timeout) callback takes the timeout value from the state and spawns a new task that we will define in a moment and calls schedule(timeout) again, building up the periodic loop. Let's implement the fake runner module:

# ./lib/background_job/database_cleaner/runner.ex

defmodule GlobalBackgroundJob.DatabaseCleaner.Runner do
  require Logger

  def execute do
    random = :rand.uniform(1_000)

    Process.sleep(random)

    Logger.info("#{__MODULE__} #{random} records deleted")
  end
end

This module fakes deleting the data logging a message with the eliminated count. Why using a task to execute this action? I like implementing these kinds of workers as simply as possible, adding only the necessary functionality to handle messages, putting any other business logic in its corresponding module, separating concerns and responsibilities. The worker module only is in charge of spawning the task and scheduling the next run, and it does not care about the task result. Let's jump into the terminal and run or new periodic server:

➜ iex -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

Interactive Elixir (1.12.0) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> GenServer.start_link(GlobalBackgroundJob.DatabaseCleaner, [timeout: 1000])

[info]  ---- [nonode@nohost] Elixir.GlobalBackgroundJob.DatabaseCleaner starting
[info]  ---- [nonode@nohost] Elixir.GlobalBackgroundJob.DatabaseCleaner scheduling for 1000ms
[info]  ---- [nonode@nohost] Elixir.GlobalBackgroundJob.DatabaseCleaner deleting outdated records...
[info]  ---- [nonode@nohost] Elixir.GlobalBackgroundJob.DatabaseCleaner scheduling for 1000ms
[info]  Elixir.GlobalBackgroundJob.DatabaseCleaner.Runner 948 records deleted
[info]  ---- [nonode@nohost] Elixir.GlobalBackgroundJob.DatabaseCleaner deleting outdated records...
.......

So far, so good. However, if we add the database cleaner server to the application's main supervision tree and start several nodes, the database cleaner process will run on each of them, and we don't want that. So how can we register it globally and only allow a single instance of the process across the cluster? Let's add the final piece of the puzzle, which consists of a new GenServer which spawns the database cleaner process registering it globally using :global, and monitors it, restarting the process again if for whatever reason it goes down:

defmodule GlobalBackgroundJob.DatabaseCleaner.Starter do
  use GenServer

  alias GlobalBackgroundJob.DatabaseCleaner

  def start_link(opts) do
    GenServer.start_link(__MODULE__, opts, name: __MODULE__)
  end

  @impl GenServer
  def init(opts) do
    pid = start_and_monitor(opts)

    {:ok, {pid, opts}}
  end

  @impl GenServer
  def handle_info({:DOWN, _, :process, pid, _reason}, {pid, opts} = state) do
    {:noreply, {start_and_monitor(opts), opts}}
  end

  defp start_and_monitor(opts) do
    pid =
      case GenServer.start_link(DatabaseCleaner, opts, name: {:global, DatabaseCleaner}) do
        {:ok, pid} ->
          pid

        {:error, {:already_started, pid}} ->
          pid
      end

    Process.monitor(pid)

    pid
  end
end

Its start_link/1 function expects the configuration options for the database cleaner process. While starting the singleton process, its init/1 function builds its internal state and calls start_and_monitor/1, which takes the opts to start the database cleaner process, using {:global, name} to register it. Whether spawning the database cleaner process succeeds or fails (because it has already started in a different node), it takes its pid, assigns it to its internal state, and monitors it. Finally, it implements the handle_info({:DOWN, ... callback, which will receive the corresponding message if the monitored process dies, calling again start_and_monitor/1 to restart it and begin the monitor loop. Let's update our application module, so it starts a singleton process on the service start:

# ./lib/background_job/application.ex

defmodule GlobalBackgroundJob.Application do
  @moduledoc false

  use Application

  @impl true
  def start(_type, _args) do
    children = [
      {Cluster.Supervisor, [topologies(), [name: GlobalBackgroundJob.ClusterSupervisor]]},
      {GlobalBackgroundJob.DatabaseCleaner.Starter, [timeout: :timer.seconds(2)]}
    ]

    # ...
  end

  # ...

If we jump to the terminal and start two different nodes, we should see the following:

# NODE 1
➜ iex --sname n1 -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

[info]  ----[n1@mbp] Elixir.GlobalBackgroundJob.Singleton starting
[info]  ----[n1@mbp] Elixir.GlobalBackgroundJob.Singleton restarting...
[info]  ----[n1@mbp] Elixir.GlobalBackgroundJob.DatabaseCleaner scheduling for 5000ms...
[info]  ----[n1@mbp] Elixir.GlobalBackgroundJob.Singleton monitoring...
[info]  ----[n1@mbp] Elixir.GlobalBackgroundJob.DatabaseCleaner deleting outdated records...
[info]  ----[n1@mbp] Elixir.GlobalBackgroundJob.DatabaseCleaner scheduling for 5000ms...
[info]  Elixir.GlobalBackgroundJob.DatabaseCleaner.Runner 979 records deleted
[info]  ----[n1@mbp] Elixir.GlobalBackgroundJob.DatabaseCleaner deleting outdated records...
[info]  ----[n1@mbp] Elixir.GlobalBackgroundJob.DatabaseCleaner scheduling for 5000ms...

# NODE 2
➜ iex --sname n2 -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.Singleton starting
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.Singleton restarting...
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.DatabaseCleaner scheduling for 5000ms...
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.Singleton monitoring...
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.Singleton starting
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.Singleton restarting...
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.Singleton ...already started!
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.Singleton monitoring...

n1 succeeds in starting the DatabaseCleaner process, whereas n2 detects that it has already begun and monitors it. If we stop n1, we can see the following in n2:

[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.Singleton process down, restarting...
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.DatabaseCleaner scheduling for 5000ms...
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.Singleton monitoring...
[info]  ----[n2@mbp] Elixir.GlobalBackgroundJob.DatabaseCleaner deleting outdated records...
....

As we planned, n2 detects that the DatabaseCleaner process in n1 died, restarting and monitoring it again. Let's check the :global registry:

iex(n2@mbp)4> :global.registered_names
[GlobalBackgroundJob.DatabaseCleaner]
iex(n2@mbp)5> :global.whereis_name GlobalBackgroundJob.DatabaseCleaner
#PID<19759.204.0>

If you play around starting new nodes, stopping them, or killing the DatabaseCleaner process, use these functions to check how the process always is registered again with a different PID.

The database cleaner process using `swarm`

Source code of this example

Swarm is a globally distributed registry architected to handle dynamic node membership and creating/removing large volumes of process registrations in short time windows. It also has some cool features like automatic distribution of processes across the cluster and easy process handoff between nodes, including their current state. The former means that when swarm moves a process to a different node, it can continue with its current state. However, implementing the singleton DatabaseCleaner process using swarm has been tricky, and I haven't figured out an optimal solution that takes advantage of its features. Nevertheless, let's create a new application, implementing the solution and see what issues do we encounter and how to solve them:

mix new swarm_background_job --sup

Let's add swarm and libcluster to its dependencies and configure libcluster's topologies:

# ./mix.exs

defmodule SwarmBackgroundJob.MixProject do
  use Mix.Project

  # ...

  defp deps do
    [
      {:libcluster, "~> 3.3"},
      {:swarm, "~> 3.4"}
    ]
  end
end

# ./lib/swarm_background_job/application.ex

defmodule SwarmBackgroundJob.Application do
  # ...

  def start(_type, _args) do
    children = [
      {Cluster.Supervisor, [topologies(), [name: SwarmBackgroundJob.ClusterSupervisor]]}
    ]
    # ...
  end

  defp topologies do
    [
      background_job: [
        strategy: Cluster.Strategy.Gossip
      ]
    ]
  end

Initially, both the DatabaseCleaner and the Runner module should be the same as in the :global registry solution, except that their namespace should start with SwarmBackgroundJob, so let's copy both modules into the new project and edit their current module name. Checking the swarm's documentation, we have to implement a supervisor which it will use to distribute the processes across the cluster, so let's go ahead and add it:

# ./lib/swarm_background_job/database_cleaner/supervisor.ex

defmodule SwarmBackgroundJob.DatabaseCleaner.Supervisor do
  use DynamicSupervisor

  def start_link(state) do
    DynamicSupervisor.start_link(__MODULE__, state, name: __MODULE__)
  end

  def init(_) do
    DynamicSupervisor.init(strategy: :one_for_one)
  end

  def start_child(opts) do
    child_spec = %{
      id: SwarmBackgroundJob.DatabaseCleaner,
      start: {SwarmBackgroundJob.DatabaseCleaner, :start_link, [opts]},
      restart: :transient
    }

    DynamicSupervisor.start_child(__MODULE__, child_spec)
  end
end

We have implemented a simple DynamicSupervisor module implementation, with a start_child/1 function that defines the child_spec of the workers it manages, in this case, our DatabaseCleaner. Please note that we use the :transient restart strategy, which restarts a child process only if it terminates abnormally. This is crucial for not duplicating the workers once swarm starts moving them around the cluster. Next, we have to add the new supervisor to the application's children:

# ./lib/swarm_background_job/application.ex

defmodule SwarmBackgroundJob.Application do
  # ...

  def start(_type, _args) do
    children = [
      {Cluster.Supervisor, [topologies(), [name: SwarmBackgroundJob.ClusterSupervisor]]},
      SwarmBackgroundJob.DatabaseCleaner.Supervisor
    ]

    # ...
  end

Since DynamicSupervisor doesn't automatically start any process on its initialization, we have to find a way of spawning the DatabaseCleaner process, register it using swarm, and supervise it using our supervisor. We could do this in the application module, after the Supervisor.start_link(children, opts) call. However, I don't particularly like adding any logic to the main application init function, so what I do is creating a helper module for these tasks:

# ./lib/swarm_background_job/database_cleaner/starter.ex

defmodule SwarmBackgroundJob.DatabaseCleaner.Starter do
  require Logger

  alias SwarmBackgroundJob.DatabaseCleaner
  alias SwarmBackgroundJob.DatabaseCleaner.Supervisor, as: DatabaseCleanerSupervisor

  def child_spec(opts) do
    %{
      id: __MODULE__,
      start: {__MODULE__, :start_link, [opts]},
      type: :worker
    }
  end

  def start_link(opts) do
    Swarm.register_name(DatabaseCleaner, DatabaseCleanerSupervisor, :start_child, [opts])

    :ignore
  end
end

Think about the Starter module as a fake GenServer implementation that any logic in its start_link/1 function and returns :ignore. Now we can add it to the main application children, and when the application starts, it will call the Swarm.register_name/4 function, passing the name, along with the module, function, and arguments, that swarm will use to start the process and register the name:

# ./lib/swarm_background_job/application.ex

defmodule SwarmBackgroundJob.Application do
  # ...

  def start(_type, _args) do
    children = [
      {Cluster.Supervisor, [topologies(), [name: SwarmBackgroundJob.ClusterSupervisor]]},
      SwarmBackgroundJob.DatabaseCleaner.Supervisor,
      {SwarmBackgroundJob.DatabaseCleaner.Starter, [[timeout: :timer.seconds(2)]]}
    ]

    # ...
  end
end

Last but not least, let's edit the DatabaseCleaner module to add the necessary callback functions required by swarm:

# ./lib/swarm_background_job/database_cleaner.ex

defmodule SwarmBackgroundJob.DatabaseCleaner do
  use GenServer

  # ...


  def handle_call({:swarm, :begin_handoff}, _from, state) do
    {:reply, :restart, state}
  end

  def handle_cast({:swarm, :resolve_conflict, _}, state) do
    {:noreply, state}
  end

  def handle_info({:swarm, :die}, state) do
    {:stop, :shutdown, state}
  end

  # ...
end

Since we don't need to manage any state handoff, we are handling the following messages:

{:swarm, :begin_handoff}: called when a handoff has initiated due to changes in cluster topology. In our particular case, :restart makes the process restart in the new node.
{:swarm, :resolve_conflict, _}: called when a network split is healed and the local process should continue running, but a duplicated process on the other side of the split hands off its state to the current.
{:swarm, :die}: sent when this process has moved to a different node. Since we don't want duplicates, we stop it.

Let's jump back to the terminal and start a node:

# NODE 1
➜ iex --sname n1 -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]
[info]  [swarm on n1@mbp] [tracker:init] started
[info]  [swarm on n1@mbp] [tracker:cluster_wait] joining cluster..
[info]  [swarm on n1@mbp] [tracker:cluster_wait] no connected nodes, proceeding without sync
[debug] [swarm on n1@mbp] [tracker:handle_call] registering SwarmBackgroundJob.DatabaseCleaner as process started by Elixir.SwarmBackgroundJob.DatabaseCleaner.Supervisor.start_child/1 with args [[[timeout: 2000]]]
[debug] [swarm on n1@mbp] [tracker:do_track] starting SwarmBackgroundJob.DatabaseCleaner on n1@mbp
[info]  ----[n1@mbp] Elixir.SwarmBackgroundJob.DatabaseCleaner scheduling for 2000ms
[debug] [swarm on n1@mbp] [tracker:do_track] started SwarmBackgroundJob.DatabaseCleaner on n1@mbp
[info]  ----[n1@mbp] Elixir.SwarmBackgroundJob.DatabaseCleaner deleting outdated records...
[info]  ----[n1@mbp] Elixir.SwarmBackgroundJob.DatabaseCleaner scheduling for 2000ms

The application starts as usual and swarm registers the database cleaner process with success, which starts doing its thing. Let's ask swarm for the registered processes:

iex(n1@mbp)2> Swarm.registered
[{SwarmBackgroundJob.DatabaseCleaner, #PID<0.244.0>}]

There it is. Let's start a new node and see what happens:

# NODE 2
➜ iex --sname n2 -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]
[info]  [swarm on n2@mbp] [tracker:init] started
[info]  [swarm on n2@mbp] [tracker:ensure_swarm_started_on_remote_node] nodeup n1@mbp
[info]  [swarm on n2@mbp] [tracker:cluster_wait] joining cluster..
[info]  [swarm on n2@mbp] [tracker:cluster_wait] syncing with n1@mbp
[debug] [swarm on n2@mbp] [tracker:cluster_wait] forking clock: {1, 0}, lclock: {{1, 0}, 0}, rclock: {{0, 1}, 0}
[info]  [swarm on n2@mbp] [tracker:awaiting_sync_ack] received sync acknowledgement from n1@mbp, syncing with remote registry
[debug] [swarm on n2@mbp] [tracker:sync_registry] local tracker is missing SwarmBackgroundJob.DatabaseCleaner, adding to registry
[info]  [swarm on n2@mbp] [tracker:awaiting_sync_ack] local synchronization with n1@mbp complete!
[info]  [swarm on n2@mbp] [tracker:resolve_pending_sync_requests] pending sync requests cleared
[debug] [swarm on n2@mbp] [tracker:handle_call] registering SwarmBackgroundJob.DatabaseCleaner as process started by Elixir.SwarmBackgroundJob.DatabaseCleaner.Supervisor.start_child/1 with args [[[timeout: 2000]]]
[debug] [swarm on n2@mbp] [tracker:do_track] found SwarmBackgroundJob.DatabaseCleaner already registered on n1@mbp

It is very similar to n1 except that swarm tries to start the process and eventually realizes it has already spawned in n1. Let's confirm we still have a single process registered:

# NODE 2
iex(n2@mbp)1> Swarm.registered
[{SwarmBackgroundJob.DatabaseCleaner, #PID<19868.244.0>}]

The PID is the same corresponding to n1, excellent! Let's start the third node:

# NODE 3

➜ iex --sname n3 -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]


[info]  [swarm on n3@mbp] [tracker:init] started
[info]  [swarm on n3@mbp] [tracker:ensure_swarm_started_on_remote_node] nodeup n1@mbp
[info]  [swarm on n3@mbp] [tracker:ensure_swarm_started_on_remote_node] nodeup n2@mbp
[info]  [swarm on n3@mbp] [tracker:cluster_wait] joining cluster..
[info]  [swarm on n3@mbp] [tracker:cluster_wait] found connected nodes: [:n2@mbp, :n1@mbp]
[info]  [swarm on n3@mbp] [tracker:cluster_wait] selected sync node: n2@mbp
[info]  [swarm on n3@mbp] [tracker:syncing] received registry from n2@mbp, merging..
[debug] [swarm on n3@mbp] [tracker:sync_registry] local tracker is missing SwarmBackgroundJob.DatabaseCleaner, adding to registry
[info]  [swarm on n3@mbp] [tracker:syncing] local synchronization with n2@mbp complete!
[info]  [swarm on n3@mbp] [tracker:resolve_pending_sync_requests] pending sync requests cleared
[debug] [swarm on n3@mbp] [tracker:handle_call] registering SwarmBackgroundJob.DatabaseCleaner as process started by Elixir.SwarmBackgroundJob.DatabaseCleaner.Supervisor.start_child/1 with args [[[timeout: 2000]]]
[debug] [swarm on n3@mbp] [tracker:do_track] starting SwarmBackgroundJob.DatabaseCleaner on remote node n2@mbp
[debug] [swarm on n3@mbp] [tracker:handle_replica_event] replica event: untrack #PID<19868.244.0>
[debug] [swarm on n3@mbp] [tracker:handle_replica_event] replicating registration for SwarmBackgroundJob.DatabaseCleaner (#PID<19869.241.0>) locally
[debug] [swarm on n3@mbp] [tracker:start_pid_remotely] SwarmBackgroundJob.DatabaseCleaner already registered to #PID<19869.241.0> on n2@mbp, registering locally

Swarm detects a new topology change in the cluster and restarts the database cleaner on n2, which starts to work again as if nothing happened. Let's check once again the registered processes:

# NODE 3
iex(n3@mbp)3> Swarm.registered
[{SwarmBackgroundJob.DatabaseCleaner, #PID<19869.228.0>}]

It now has a different PID. If we shut down n2, we can see how swarm detects a new change and restarts the process in one of the remaining nodes. Everything is working like in the first example using :global, let's start all the nodes again and force kill the cleaner process and see what happens:

# NODE 3
iex(n3@mbp)3> Swarm.registered
[{SwarmBackgroundJob.DatabaseCleaner, #PID<19869.234.0>}]
iex(n3@mbp)4> SwarmBackgroundJob.DatabaseCleaner |> Swarm.whereis_name |> GenServer.call(:kaboom)
# ...lots of errors
# ...process restarts in the same node
iex(n3@mbp)4> Swarm.registered
[]

The process explodes, and since we are supervising, it gets restarted. However, if we check again for the registered process in swarm it returns an empty list. If we start a new node, a new database cleaner process starts, having two different ones running across the cluster. How come? It turns out that swarm does not re-register processes that die and restart outside its handoff flow. Therefore, although the process continues thanks to its supervisor, it does not exist anymore for swarm, making it possible to have more than one instance at a time. Luckily, Elixir gives us the tools to fix this, so let's get to it. First of all, let's change the dynamic supervisor so that it does not restart any child process at all, no matter how it dies:

# ./lib/swarm_background_job/database_cleaner/supervisor.ex

defmodule SwarmBackgroundJob.DatabaseCleaner.Supervisor do
  # ...

  def start_child(opts) do
    child_spec = %{
      # ...
      restart: :temporary
    }

    DynamicSupervisor.start_child(__MODULE__, child_spec)
  end

end

Secondly, and taking a similar approach we did in the GlobalBackgroundJob.DatabaseCleaner.Starter, let's refactor the Starter module like so:

# lib/swarm_background_job/database_cleaner/starter.ex

defmodule SwarmBackgroundJob.DatabaseCleaner.Starter do
  # ..

  def start_link(opts) do
    GenServer.start_link(__MODULE__, opts, name: __MODULE__)
  end

  @impl GenServer
  def init(opts) do
    {:ok, opts, {:continue, {:start_and_monitor, 1}}}
  end

  @impl GenServer
  def handle_continue({:start_and_monitor, retry}, opts) do
    case Swarm.whereis_or_register_name(
           DatabaseCleaner,
           DatabaseCleanerSupervisor,
           :start_child,
           [opts]
         ) do
      {:ok, pid} ->
        Process.monitor(pid)

        {:noreply, {pid, opts}}

      other ->
        Process.sleep(500)

        {:noreply, opts, {:continue, {:start_and_monitor, retry + 1}}}
    end
  end

  @impl GenServer
  def handle_info({:DOWN, _, :process, pid, _reason}, {pid, opts}) do
    {:noreply, opts, {:continue, {:start_and_monitor, 1}}}
  end
end

The Starter module is now a real GenServer, which instead of registering the database cleaner process on its start_link/1 function and returning :ignore, it starts like any other generic server. The init/1 callback function function returns a tuple containing opts and {:continue, {:start_and_monitor, 1}, which leads us to the handle_continue({:start_and_monitor, retry}, opts) callback, in which calls Swarm.whereis_or_register_name/4 which finds the current PID of the process, registering it if it does not exist. If everything goes fine, it monitors the resulting PID. Otherwise, it sleeps for 500 milliseconds and returns {:continue, {:start_and_monitor, retry + 1}, forcing a new monitoring retry. Finally, it implements the handle_info({:DOWN, ... callback, triggered when the monitored process dies, entering in the register + monitor loop again. Let's try out these changes by starting the three different nodes and killing the process like we previously did:

# NODE 3
iex(n3@mbp)1> Swarm.registered
[{SwarmBackgroundJob.DatabaseCleaner, #PID<19949.240.0>}]
iex(n3@mbp)2> SwarmBackgroundJob.DatabaseCleaner |> Swarm.whereis_name |> GenServer.call(:kaboom)
# ...lots of errors
# ...process restarts in the same node
iex(n3@mbp)2> Swarm.registered
[{SwarmBackgroundJob.DatabaseCleaner, #PID<19949.247.0>}]

If you play around with starting new nodes, stopping the current one, and killing the process, you can verify that the process keeps starting with no duplicates.

The database cleaner process using `horde`

Source code of this example

The last registry that we are going to be looking at is horde. Inspired by swarm, it addresses some of its deficiencies, like clearly separating the registration and supervision of processes, among others. Let's jump straight into the terminal and create a new project, add the necessary dependencies, and configure libcluster:

mix new horde_background_job --sup

# ./mix.exs

defmodule HordeBackgroundJob.MixProject do
  use Mix.Project

  # ...

  defp deps do
    [
      {:libcluster, "~> 3.3"},
      {:horde, "~> 0.8.3"}
    ]
  end
end

# ./lib/horde_background_job/application.ex

defmodule HordeBackgroundJob.Application do
  # See https://hexdocs.pm/elixir/Application.html
  # for more information on OTP Applications
  @moduledoc false

  use Application

  @impl true
  def start(_type, _args) do
    children = [
      {Cluster.Supervisor, [topologies(), [name: BackgroundJob.ClusterSupervisor]]}
    ]

    # ...
  end

  defp topologies do
    [
      background_job: [
        strategy: Cluster.Strategy.Gossip
      ]
    ]
  end
end

Suppose we want horde to work in a dynamic cluster like in our case. In that case, we need to add three different modules to our application, which correspond to a supervisor, a registry, and a node listener which sticks everything together. Let's start by implementing the supervisor:

# ./lib/horde_background_job/horde_supervisor.ex

defmodule HordeBackgroundJob.HordeSupervisor do
  use Horde.DynamicSupervisor

  def start_link(_) do
    Horde.DynamicSupervisor.start_link(__MODULE__, [strategy: :one_for_one], name: __MODULE__)
  end

  def init(init_arg) do
    [members: members()]
    |> Keyword.merge(init_arg)
    |> Horde.DynamicSupervisor.init()
  end

  def start_child(child_spec) do
    Horde.DynamicSupervisor.start_child(__MODULE__, child_spec)
  end

  defp members() do
    Enum.map([Node.self() | Node.list()], &{__MODULE__, &1})
  end
end

Using Horde.DynamicSupervisor under the hood, it computes all the members in the cluster while starting. We have also added the start_child(child_spec) function, convenient for creating and supervising new processes. Let's go ahead and add the registry module:

# ./lib/horde_background_job/horde_registry.ex

defmodule HordeBackgroundJob.HordeRegistry do
  use Horde.Registry

  def start_link(_) do
    Horde.Registry.start_link(__MODULE__, [keys: :unique], name: __MODULE__)
  end

  def init(init_arg) do
    [members: members()]
    |> Keyword.merge(init_arg)
    |> Horde.Registry.init()
  end

  defp members() do
    Enum.map([Node.self() | Node.list()], &{__MODULE__, &1})
  end
end

As the supervisor, the registry starts a Horde.Registry computing all the available nodes. How do the supervisor and registry consider changes in the cluster topology when get nodes added or removed? Here is where the node observer module comes into play:

# ./lib/horde_background_job/node_observer.ex

defmodule HordeBackgroundJob.NodeObserver do
  use GenServer

  alias HordeBackgroundJob.{HordeRegistry, HordeSupervisor}

  def start_link(_), do: GenServer.start_link(__MODULE__, [])

  def init(_) do
    :net_kernel.monitor_nodes(true, node_type: :visible)

    {:ok, nil}
  end

  def handle_info({:nodeup, _node, _node_type}, state) do
    set_members(HordeRegistry)
    set_members(HordeSupervisor)

    {:noreply, state}
  end

  def handle_info({:nodedown, _node, _node_type}, state) do
    set_members(HordeRegistry)
    set_members(HordeSupervisor)

    {:noreply, state}
  end

  defp set_members(name) do
    members = Enum.map([Node.self() | Node.list()], &{name, &1})

    :ok = Horde.Cluster.set_members(name, members)
  end
end

The node observer module is a simple GenServer that subscribes to the cluster's changes using :net_kernel.monitor_nodes/2 just like we did in the first part of the series. On receiving any change, it gets the current available nodes and updates both the supervisor and registry using Horde.Cluster.set_members(name, members).

We have everything we need to run a cluster under horde, so let's add these modules to the main supervision tree:

# .lib/horde_background_job/application.ex

defmodule HordeBackgroundJob.Application do
  # ...

  def start(_type, _args) do
    children = [
      {Cluster.Supervisor, [topologies(), [name: BackgroundJob.ClusterSupervisor]]},
      HordeBackgroundJob.HordeRegistry,
      HordeBackgroundJob.HordeSupervisor,
      HordeBackgroundJob.NodeObserver
    ]

    # ...
  end

  # ..
end

To speed up things since this post has gone out of hands, let's copy the swarm's application DatabaseCleaner and the DatabaseCleaner.Runner modules into the current module, renaming their corresponding namespaces to HordeBackgroundJob. Finally, let's implement the module that spawns the cleaner process under horde:

# lib/horde_background_job/database_cleaner/starter.ex

defmodule HordeBackgroundJob.DatabaseCleaner.Starter do
  require Logger

  alias HordeBackgroundJob.{DatabaseCleaner, HordeRegistry, HordeSupervisor}

  def child_spec(opts) do
    %{
      id: __MODULE__,
      start: {__MODULE__, :start_link, [opts]},
      type: :worker,
      restart: :temporary,
      shutdown: 500
    }
  end

  def start_link(opts) do
    name =
      opts
      |> Keyword.get(:name, DatabaseCleaner)
      |> via_tuple()

    new_opts = Keyword.put(opts, :name, name)

    child_spec = %{
      id: DatabaseCleaner,
      start: {DatabaseCleaner, :start_link, [new_opts]}
    }

    HordeSupervisor.start_child(child_spec)

    :ignore
  end

  def whereis(name \\ DatabaseCleaner) do
    name
    |> via_tuple()
    |> GenServer.whereis()
  end

  defp via_tuple(name) do
    {:via, Horde.Registry, {HordeRegistry, name}}
  end
end

Using the same fake GenServer technique we did in the swarm implementation, it takes the name from the received options and builds a tuple in the form of {:via, Horde.Registry, {HordeRegistry, name}} to set it again and use the resulting options to call the HordeSupervisor.start_child(child_spec) function that we defined previously. The tuple containing the name specifies how we want to register the process, in our case using the Horde.Registry under the HordeBackgroundJobs.HordeRegsitry. He have also defined a whereis function to help us finding the process while testing. Let's add the starter module to the application start:

# .lib/horde_background_job/application.ex

defmodule HordeBackgroundJob.Application do
  # ...

  def start(_type, _args) do
    children = [
      # ...
      {HordeBackgroundJob.DatabaseCleaner.Starter,
       [name: HordeBackgroundJob.DatabaseCleaner, timeout: :timer.seconds(2)]}
    ]

    # ...
  end

  # ..
end

We already have all the necessary pieces of the puzzle, so let's start some nodes and see what happens:

# NODE 1

➜ iex --sname n1 -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

[info]  Starting Horde.RegistryImpl with name HordeBackgroundJob.HordeRegistry
[info]  Starting Horde.DynamicSupervisorImpl with name HordeBackgroundJob.HordeSupervisor
[info]  ----[n1@mbp-#PID<0.253.0>] Elixir.HordeBackgroundJob.DatabaseCleaner scheduling for 2000ms
[info]  ----[n1@mbp-#PID<0.253.0>] Elixir.HordeBackgroundJob.DatabaseCleaner deleting outdated records...
[info]  ----[n1@mbp-#PID<0.253.0>] Elixir.HordeBackgroundJob.DatabaseCleaner scheduling for 2000ms

# NODE 2

➜ iex --sname n2 -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

[info]  Starting Horde.RegistryImpl with name HordeBackgroundJob.HordeRegistry
[info]  Starting Horde.DynamicSupervisorImpl with name HordeBackgroundJob.HordeSupervisor

# NODE 3

➜ iex --sname n3 -S mix
Erlang/OTP 24 [erts-12.0.1] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

[info]  Starting Horde.RegistryImpl with name HordeBackgroundJob.HordeRegistry
[info]  Starting Horde.DynamicSupervisorImpl with name HordeBackgroundJob.HordeSupervisor

iex(n3@mbp)1> HordeBackgroundJob.DatabaseCleaner.Starter.whereis
#PID<20046.239.0>

Let's kill the process:

iex(n3@mbp)6> HordeBackgroundJob.DatabaseCleaner.Starter.whereis |> GenServer.cast(:kaboom)
:ok
iex(n3@mbp)7> HordeBackgroundJob.DatabaseCleaner.Starter.whereis
#PID<20046.590.0>

The process dies in its current node but gets restarted thanks to Horde's supervisor, and most importantly, the registry does not lose track of its new PID, yay!

Foreword

In this part of the series, we have seen how to implement a periodic singleton process thanks to three different global registries. Using :global has been the easiest and more straightforward one of the three. However, it is also known for not recovering correctly after netsplits, thus having alternatives like swarm or horde. Between these last two, swarm looks very promising, especially its handoff mechanism. However, the amount of issues and lack of activity in its repo makes it not very reliable in the end. Finally, horde, although having to build some boilerplate to use it, feels like the perfect balance between the former two. What do you think?

In the next part of the series, we will continue with the second real-world example of distributed Elixir. We will build a download manager taking advantage of what we have learned so far and Phoenix's PubSub. In the meantime, you can check the full code of every example of this part in the link below.

Happy coding!