Refactor: Split out LogWriter from Events (no logic change)

[johnnyshields]

This PR splits the Puma::Events object into two separate objects, Events and LogWriter.

Currently the Events object combines two completely unrelated responsibilities:

• Register and callback "hooks" for internal events, like :on_booted
• Perform logging, including info/warn/debug.

These two concerns have no dependency on each other, so they should be separate objects. As Puma newbie, the fact that logging functionality was in the Events class gave me the mistaken impression that logging somehow used the same callback hooks that events do. When the @events object is passed into other classes, it's also not clear for which of these responsibilities it will be used.

This PR does not change any application logic, but it does change the constructor interface of some classes, most notably Puma::Server (it adds an extra arg for a LogWriter instance.)

[johnnyshields]

@nateberkopec This PR is likely to break as other PRs are merged, so I'd like to get a preliminary review to confirm the Puma team accepts this change in principle.

[nateberkopec]

I love it! We could take this even further: if you moved lines 83+ from log_writer.rb into their own object or somewhere else, then at that point I think you could just rename LogWriter to Logger and inherit from < ::Logger and clean this up completely. What do you think about that?

[johnnyshields]

LogWriter to Logger and inherit from < ::Logger and clean this up completely

Wow, yeah! That would be the ultimate! Was trying to minimize change.

That being said, lets do it as a series of two PRs.

[nateberkopec]

This is shippable for me when the tests pass

[johnnyshields]

@nateberkopec this is ready to merge. Appreciate if we can merge this first before other PRs because it's likely to have conflicts.

[elia]

@nateberkopec thoughts on adding this PR to the breaking changes section of the v6 changelog in light of teamcapybara/capybara#2590?

[dentarg]

@elia Sure, just make a PR

[johnnyshields]

@nateberkopec not sure if Puma is following this but I've seen other repos use a code annotation @api private for methods/classes that should be considered private, even though in terms of Ruby the methods are public. This will prevent heartbreak in terms of third party libraries expecting classes like LogWriter to be a "stable public API".

[elia]

@johnnyshields good call, would be great if, in addition to marking them as private, a public api that covers that use case was also offered.

[MSP-Greg]

@api private is essentially the Yard equivalent of RDoc's :nodoc:. Recently, a few classes/modules had :nodoc: added to them, see PR #2988.

I don't think that LogWriter should be made :nodoc: / @api private. Using Puma in standard way, it probably could be private, but Puma is often used in test frameworks like capybara, where a Puma Server is started using Server.new. That needs LogWriter...

EDIT:
To clarify (as some of this stuff is pretty 'pounded into my head'), in Puma 5 and earlier, Server.new had a parameter that was an Events object. In Puma 6, Events was split, and all methods that wrote to a log were moved to LogWriter. To keep the parameters the same, the LogWriter was added to the config/options hash parameter. If the key doesn't exist, a LogWriter.stdio is created. Test frameworks often want server output silenced, so that isn't appropriate.

It is still a breaking change, in that code to create a Server with Puma 5 and earlier will not work with Puma 6.