Mix project: how to control whether the application is started based on config

TL;DR:

I want to customize whether a Mix project will start its application automatically based on user-provided configuration.

More details

I maintain an Elixir package that is meant to be used as a dependency in host applications. My package is configured to start an OTP application that encapsulates its own supervision tree.

I’m working on providing more control over the start behaviour of the package’s OTP application.

At the moment it’s a “batteries included” package that can work with zero config. Just add it as a dependency to your Mix project, and it works.

I would like to change that to provide this API:

First, tell the package to not start its OTP application:

# An application's config file.
use Config
config :fun_with_flags, start_application: false

Then, manually put the package’s supervisor module in a supervision tree of your choice, for example:

  def start(_type, _args) do
    children = [
      HelloWorld.Repo,
      {Phoenix.PubSub, name: HelloWorld.PubSub},
      HelloWorldWeb.Endpoint,
+     FunWithFlags.Supervisor
    ]

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

I’m trying to achieve this by doing something like this:

defmodule FunWithFlags.Application do
  use Application

  def start(_type, _args) do
+   if application_should_start? do
      FunWithFlags.Supervisor.start_link(nil)
+   end
  end

+ def application_should_start? do
+   Application.get_env(:fun_with_flags, :start_application, true)
+ end
end

That however fails with this error:

** (Mix) Could not start application fun_with_flags: FunWithFlags.Application.start(:normal, []) returned a bad value: nil

I’ve looked at the docs for the Application.start/2 callback and I can’t see any return value that would communicate “nope, nothing to do and it’s ok”. So I suppose that that’s not the right way to do it.

I’ve thought that maybe I can provide the config API described above, and then tell users of my package to tell their host applications to not start the dependency automatically, but that also doesn’t seem possible. At least, I’ve looked at the docs for the application/0 function in the Mixfile, but I can’t see anything useful there.

I suppose that a workaround could be this:

  def start(_type, _args) do
+   if application_should_start? do
      FunWithFlags.Supervisor.start_link(nil)
+   else
+     # start a bogus process that does nothing
+   end
  end

But I wonder if there is a simpler and more idiomatic way to accomplish what I need that I’m just missing.

Optional extra context

The reason I’m trying to do this is to address an occasional issue. More specifically, sometimes there is a race condition when the package’s OTP application starts much faster than some of the host application’s processes. (issue on GitHub)

This is unfortunate, but my package depends (with some configurations) on some injected processes (e.g. a Phoenix.PubSub process), and it’s a bit difficult to change that. Or, rather, I find it a less elegant solution so I would prefer to implement the API described above, if possible.

I have a similar approach in my ex_money library where the exchange rate service can run it its own supervisor tree (batteries included) or be configured into the consuming app’s supervision tree, or not run at all.

The application code might give you some ideas.

You can also have your consumers configure your library as runtime: false in deps. I document this here - it prevents the host application from starting your library’s application at its application start.

4 Likes

Ah, runtime: false might do the trick! Thank you. I could document that my package needs to be added as a dependency with that option if users want to manage the supervision tree directly.

I’ve also just noticed this in those docs:

:included_applications - specifies a list of applications that will be included in the application. It is the responsibility of the primary application to start the supervision tree of all included applications, as only the primary application will be started. A process in an included application considers itself belonging to the primary application.

Maybe this will work too. I’ll try it and report back.

If that’s the case I’m wondering why you don’t switch to userland supervision completely? As a user I prefer one way of using a library – even if more involved for some use-cases – over two ways of using it, maybe even with similar but slightly different means of setting both ways up.

2 Likes

I considered it, and I think that’s something I’ll do for v2.0.

For now, I’m forcing myself to not introduce breaking changes. I would like this to be a simple update that provides this extra capability without forcing users of the package to change their setup.

That’s also why I’m trying to research the most idiomatic way to accomplish this, rather than throwing it over the wall with a clunky solution.

1 Like

I’ll second what @LostKobrakai has said. Provide a supervisor tree-less pure library that require the user to put your process under their supervision tree, then make another hex package, a thinly wrapped application that depend on the first package, to be compatible with your earlier release.

Now your users can simply pick one out of two ways to use your library by picking which hex package in deps.

I appreciate the suggestion, but that sounds even more complicated and I think it would result in a very unfriendly update experience. It might be fine for a brand new package, but I don’t think it’s the right solution for me.