Skip to content
define and enforce boundaries in Elixir projects
Elixir
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config kick off Aug 12, 2019
demos/my_system kick off Aug 12, 2019
images kick off Aug 12, 2019
lib kick off Aug 12, 2019
test kick off Aug 12, 2019
.formatter.exs kick off Aug 12, 2019
.gitignore kick off Aug 12, 2019
.tool-versions kick off Aug 12, 2019
LICENSE kick off Aug 12, 2019
README.md kick off Aug 12, 2019
boundaries.exs kick off Aug 12, 2019
mix.exs kick off Aug 12, 2019
mix.lock kick off Aug 12, 2019

README.md

Boundaries

Mix compiler which allows you to define and enforce boundaries in your Elixir projects without needing to turn your code into an umbrella application. Compared to umbrellas, boundaries requires much less ceremony, while giving you a finer-grained control over cross-module dependencies.

Status

Highly experimental, untested, and unstable.

Documentation

For a detailed reference check the compiler docs.

Basic usage

To use this library, you first need to define the boundaries of your project. A boundary is a named group of one or more modules. Each boundary exports some (but not all!) of its modules, and can depend on other boundaries. During compilation, the boundary compiler will find and report all cross-module function calls which are not permitted according to the boundary configuration.

Example

Boundaries are configured in the boundaries.exs file in the root folder of the project. Here's an example configuration:

[
  {MySystem, deps: [], exports: [User]},
  {MySystemWeb, deps: [MySystem], exports: [Endpoint]},
  {MySystem.Application, deps: [MySystem, MySystemWeb]}
]

The configuration above defines three boundaries: MySystem, MySystemWeb, and MySystem.Application.

Boundary modules are determined automatically from the boundary name. For example, the MySystem boundary contains the MySystem module, as well as any module whose name starts with MySystem. (e.g. MySystem.User, MySystem.User.Schema, ...).

The configuration specifies the following rules:

  • Modules residing in the MySystemWeb boundary are allowed to invoke functions from modules exported by the MySystem boundary.
  • Modules residing in the MySystem.Application namespace are allowed to invoke functions from modules exported by MySystem and MySystemWeb boundaries.

All other cross-boundary calls are not permitted.

Next, you need to add the mix compiler:

defmodule MySystem.MixProject do
  use Mix.Project

  def project do
    [
      compilers: [:phoenix, :gettext] ++ Mix.compilers() ++ [:boundaries],
      # ...
    ]
  end

  # ...
end

Boundary rules are validated during compilation. For example, if we have the following code:

defmodule MySystem.User do
  def auth do
    MySystemWeb.Endpoint.url()
  end
end

The compiler will emit a warning:

$ mix compile

warning: forbidden call to MySystemWeb.Endpoint.url/0
  (calls from MySystem to MySystemWeb are not allowed)
  lib/my_system/user.ex:3

The complete working example is available here.

Because boundaries is implemented as a mix compiler, it integrates seamlessly with editors which can work with mix compiler. For example, in VS Code with Elixir LS:

VS Code warning 1

VS Code warning 2

Roadmap

  • support nested boundaries (defining internal boundaries within a boundary)
  • validate calls to external deps (e.g. preventing Ecto usage from MySystemWeb, or Plug usage from MySystem)
  • support Erlang modules

License

MIT

You can’t perform that action at this time.