I’d like to announce a small library called boundaries.
This is an experimental project which explores the idea of enforcing boundaries in Elixir projects without requiring the extra ceremony of umbrella apps. You can find a brief explanation on the library repo, while a more detailed doc is available here.
Note that this library is still in an exploratory phase, and I haven’t really tried it out myself yet. At this point I’m opening it primarily to collect the community feedback.
This looks very nice! I hope to find some time to play with it soon.
One question I had while reading. I was wondering what the reason is that the root module is always exported?
This is exactly how I imagine boundries to be reasonably enforced and it’s even part of elixir LS.
There are two reasons. One is mechanical, another conceptual.
The mechanical is that allowing root export to be configurable makes configuration a bit more messy. For example, let’s say we want to export MySystem and MySystem.User. There are two options:
{MySystem, exports: [MySystem, MySystem.User]}
Here, we require that the exported modules are referenced with the full name which makes the configuration more noisy. It can become a significant problem if we’re dealing with 2nd (or 3rd, or 4th, …) level boundaries (which is an addition I’m definitely considering).
Another option is to introduce some sort of special atom such as :this, or :root:
{MySystem, exports: [:root, MySystem.User]}
which looks a bit ugly/hacky to me.
The conceptual problem is that I’m somewhat skeptical that exporting e.g. MySystem.User, while keeping MySystem internal is a good code organization. If you want to have some internal helper functions, I think that using e.g. MySystem.Helpers or some such is a better approach. To be clear, I definitely don’t want boundaries to be highly opinionated and rigid, but given the mechanical issues presented earlier, and this conceptual problem, I currently opted to always export the root module.
In any case, none of the current choices is set in stone, so this decision is definitely up for discussion (in which case perhaps a GH issue would be a better place).
I was just wondering about the the reasons. Both reasons look valid.
Elixir LS has support for boundaries? Where can I read about that?
Look at the github readme.
I think that what @LostKobrakai tries to say is that boundaries integrates with ElixirLS, because it’s a mix compiler, and ElixirLS can work with mix. This is mentioned in the boundaries readme near the end:
Ah, now I get it. Thanks. I completely misinterpreted that.
First off this is a VERY interesting project! It’s really neat to be able to define enforced boundaries in such a succinct way. A tool like this could help an Elixir project stay in one application for much longer before feeling a need to move to an umbrella or poncho style with multiple applications.
I agree that it makes sense to export the root module by default. But in order to have a flexible tool it would be nice to optionally not export a root module. Perhaps a syntax like this could work:
{MySystem, exports: [MySystem.User], export_root: false}
Looking at this on my phone, but I didn’t see it mentioned anywhere how this interacts with the standard library and packages. Do they also need to be defined as boundaries? Also, I suspect this wouldn’t catch modules passes as variables? Would it notice you reference a module to store it into a variable?
This is a great project. I ran it against a small app I’ve been working on and found a couple of useful violations. Definitely think something like this has legs.
If others run into a bug when reporting on .eex files I posted a fix in GitHub.
This is a nice solution, thanks!
I guess my question would be: what is the scenario where you want to export submodules and keep the root module internal?
External code, as well as internal Erlang modules are currently not considered, so you don’t need to (in fact you can’t) define those as boundaries.
I’m definitely thinking about adding the support for deps, which would allow us to e.g. prevent Plug calls from the business logic.
The implementation uses Mix.Tasks.Xref.calls to get a list of cross-module references. My understanding is that this will include any reference to another module, not just a function call.
I’ve also confirmed this experimentally. As explained in this paragraph, if in MySystem.App you have a reference to MySystemWeb.Endpoint, it will be treated as a cross-module dependency, even though there’s no function call.
Looks great!
My ¢2.
I think the suggestions for decoupling / establishing boundaries might bring a huge value to it. We might have a configurable threshold (default 1 or like) and if the Xref.calls <= @threshold the library might issue a suggestion to decouple things.
Also, finding orphans might be valuable as well.
Interesting suggestions, thanks!
More generally, I think that explicit boundaries open up potential for some interesting tools, such as producing a boundary dependency graph (which in a large project should be easier to grasp), or automatic extraction of a boundary into a separate project, in the cases where you want to split your project.
@sasajuric I’m very happy to see this problem tackled. There’s a great potential in Elixir for not just defining but also reliably validating cross-module dependencies.
I myself have attempted to tackle it via static analysis (Credo check) and with a different approach towards defining a boundary (as any module with @moduledoc and its children). You can find a well-documented code here. We didn’t use it though due to me then discovering mix xref as proof of compiler acting as way better tool for tracking calls (which you’ve used) and for the @moduledoc approach being not flexible enough (which your solution is).
I have a few questions that come from my my experiences with the above attempt:
Did you consider a decentralized solution towards defining boundaries - i.e. one in which the boundary root somehow (e.g. via module attribute) marks itself as such and somehow defines its exports as opposed to your boundaries.exs? In such solution exports could also be auto-inferred by tracking references from the root i.e. all modules exposed by root become part of the contract and validated (exports still must be marked as such in order to avoid mistakes).
Did you consider taking leverage of @moduledoc in any way? For instance you could consider all modules of 3rd party library that do have moduledoc (which can be checked after compilation) to be “exports” of the library. This seems to be a convention of Elixir although from my experience, developers are not that aware of this, so it may be a risky route to follow.
Even though you seem to advertise your library as kind of an alternative to umbrella I think both aren’t mutually exclusive and solve different problems. As such your library is IMO 100% viable for use in umbrella project. And so my question: do you plan to support umbrella projects in the library (like mix xref does via special options)?
Is it possible to have some parts of the code that are blacklisted from the check i.e. that could call anything or that could be called by anything. Does the library support such cases? It would be useful for larger projects that are in process of defining better boundaries but still having some “legacy” code that just can’t follow them. I think there’s a room in the documentary part of your project for tackling such conceptual problems.
Again thanks for the great effort and looking forward for your insights on the above.
Great questions, thanks!
TBH I didn’t. This simple exs was a first thing that came to mind 
But now that you mention it, if we think about larger projects where developers want to be fine grained and so create a larger number of boundaries, I think that a decentralized approach would definitely scale better than a single .exs file which would possibly become bloated.
I guess a big unknown for me at this point is do we expect such fine granularity? I’d typically expect a much smaller amount of boundaries compared to the number of modules. And if I’m right, then perhaps a centralized solution might be simpler.
OTOH, I do have some ideas to support sub-boundaries (internal boundaries within boundaries), and for that approach, I think that decentralized definitely seems like a better option.
Another win for decentralized is that you don’t need to sync another file. So for example, if you delete or rename a module, the boundary info is auto updated.
One small issue with decentralized is that a root module always has to exist. So if I don’t have a root module, I need to create it for the sole purpose of having a boundary. Perhaps that’s fine.
Also, the usage would then probably look like:
defmodule MyBoundary do
use Boundary,
exports: [...],
deps: [...]
end
Which, under the hood would be persisted to BEAM, so they can be collected by the boundaries checker.
I’m a bit unhappy about using use, but ATM I don’t see a simple solution which isn’t built on use.
No, but that’s an interesting idea, thanks! I’ll keep it in mind.
Absolutely agree! I advertise it as an alternative to umbrella for specifying and enforcing boundaries. Nothing more than that 
In theory, it already works (compiler is marked as recursive). In practice, I have no idea because I haven’t tested it If boundaries in umbrella projects don’t work, open up an issue on the repo.
Currently no, but you make good argument why this might make sense.
+1 to supporting deps. I currently have an umbrella project I’d like to move into a normal project, and having more fine grained deps checks would be helpful.
As a side comment related to the motivation to avoid the extra ceremony of umbrella projects, my understanding is that an umbrella project is required if you want to deploy different apps to different boxes, since mix handles the creation of .app files and currently can only do so from a mix.exs file. So in my case I’m planning on storing all of my application logic in one app of the umbrella project and then using the other apps just for mix.exs and supervision tree details for the respective OTP applications. The use of boundaries within the main app will be helpful in keeping the code clean and keeping me honest about where I’m using my external dependencies.
Thanks for sharing the library!
I obviously need to improve the project readme
I’m not suggesting that umbrellas are bad in general. They do require extra ceremony, but if you have the problem which they solve, then it’s fine to pay the price.
However, drawing boundaries is, in my view, not the problem umbrellas are supposed to solve. The main hypothesis behind this experiment is that umbrellas are not needed for enforcing boundaries, and that it’s possible to write a tool which solves the same problem in a simpler way (hence, less ceremony), which is at the same time more powerful.
Your readme is great. I was just explaining how boundaries will help me with my specific challenges, and I decided to share why I need an umbrella project, in part because I’m hoping someone will correct my understanding and tell me it’s possible to have multiple OTP apps in a normal project. 
© Copyright Elixir Forum | Terms | Privacy & Cookies
