Public API of (Gen)servers

[revolko]

The question is simple:

Should public API of any server be implemented in the server module or in the separate module?

Originally posted by @Puckoland in #24 (comment)

[Puckoland]

To continue the discussion: I guess it depends 😄

You mentioned phoenix in the comments. There the API is separated, but only with comments ## Socket API, ## Channel API, which is exactly what I do not like about it.
It worsens readability and testability in my view (e.g. if you wanted to test FilePublisher's handle_message and wanted to mock GenServer (so it does not actually write to file, but it returns the message instead, for example)).

Maybe a bit off topic from GenServer, but they also use "public API" and their implementations.
They use pubsub, which provides the public API (subscribe, broadcast, etc.), but internally, it delegates to modules like Phoenix.PubSub.PG2 or Phoenix.PubSub.Redis, which implements is (it is an adapter).

I found some post discussing exactly this. And why we should separate it.

It seems that official [documentation](implemented in two parts) supports both:

A GenServer is implemented in two parts: the client API and the server callbacks. You can either combine both parts into a single module or you can separate them into a client module and a server module. The client is any process that invokes the client function. The server is always the process identifier or process name that we will explicitly pass as argument to the client API. Here we'll use a single module for both the server callbacks and the client API.

[revolko]

You mentioned phoenix in the comments. There the API is separated, but only with comments ## Socket API, ## Channel API, which is exactly what I do not like about it.
It worsens readability and testability in my view (e.g. if you wanted to test FilePublisher's handle_message and wanted to mock GenServer (so it does not actually write to file, but it returns the message instead, for example)).

That's really interesting. Honestly, for me that file is actually nice to read. What I like most about it is that everything is in the same place and I don't need to jump around different files. About testability I cannot really say much. The only thing I remember from elixir doc is that they discourage mocking (I guess everyone does 😄 ). But I have no idea if they provide some kind of alternative or ways to test.

Nice article. I like the fact that for each implementation there is a clear structure (I should start thinking about that more). However, when looking at the provided implementation IMO the code is very confusing. You have to jump between 3 files to get to the implementation (I guess it would be much nicer if they did not use Impl modules).

That brings me to those phoenix examples that you have posted. IMO the distinction is that those files are API of the library. We should distinguish if we are talking about internal implementation of the server that should be used only by other internal (possibly public API) modules, or if the given server will be directly used by other out of the project modules. I agree that if the server is going to be used by some out of the project code (making it really library and not application) it is good to provide public API.