-
Notifications
You must be signed in to change notification settings - Fork 39
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
HOCON 3.0 Specification #267
Labels
Milestone
Comments
Aaronontheweb
added
usability
akkadotnet-compat
Legacy compatibility with Akka.Configuration
labels
Mar 10, 2020
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
HOCON 3.0 Specification
In the previous releases of HOCON, we let the OSS project do its own thing without any plan for integrating it into Akka.NET and replacing the stand-alone HOCON engine built into the
Akka.Configuration.Config
class. This was a mistake and led to us having to drop stand-alone HOCON integration as part of the Akka.NET v1.4.1 milestone.Motivation for Moving to Stand-alone HOCON
Why bother moving from
Akka.Configuration.Config
? Isn't it good enough as is? Why support an entire configuration library?The motivations for separating HOCON from Akka.NET are the following:
Akka
package, which is whereAkka.Configuration.Config
is housed. If we want to innovate around configuration, it's very expensive for us to do this without separating the libraries into their own projects.Microsoft.Extensions.Configuration
namespace. We're opposed to taking a dependency on such a library directly inside Akka.NET itself (OSS hygiene) - but if we could consumeMicrosoft.Extensions.Configuration
and use that to generate a HOCONConfig
object prior to starting anActorSystem
, that could be done easily in a separate library.HOCON 2.0 and Earlier
HOCON 2 and earlier releases of HOCON were developed without a formal plan for introducing them in a non-breaking way into Akka.NET, the biggest consumer of HOCON currently. This will be remedied in HOCON 3.0.
However, our plan is to deprecate HOCON 2 as quickly as possible and move onto HOCON 3 using the spec contained herein.
HOCON 3.0 Development Plan
The HOCON 3.0 development will comport to the following rules and requirements:
Functional Requirements
Config
behaviors must support the previous behavior contract ofAkka.Configuration.Config
- ifConfig.GetString(string hoconPath)
didn't throw an exception whenhoconPath
was not found inside the currentConfig
object, the new HOCONConfig
shouldn't either.IHoconConfig
, and that interface will be implemented on bothHOCON.Config
andAkka.Configuration.Config
with matching behaviors.Config
objects must be immutable and read-only once they are returned from theConfigurationFactory
or equivalent parser / loader class.Config
class should produce as few object allocations as possible - preferably zero.public Config Config.Merge()
call or equivalent is made explicitly by the caller.Akka.Configuration.Config
should be able to switch to a new version of Akka.NET that uses the stand-alone HOCON NuGet package without modifying any code or configuration (except for invalid HOCON that the previous parser didn't enforce.)Testing Requirements
Akka.Configuration.Config
test suite must pass, unless that feature is explicitly being deprecated or is already obsolete.Config
class must be benchmarked on each pull request using an NBench or equivalent test suite. Specifically we must measure throughput, memory allocation, and garbage colletion:WithFallback(Config c)
IHoconConfig
must be tested using identical behavior specifications to ensure consistent behavior across implementations.IHoconConfig
compatibility has been added.Config
object while new fallbacks are being added to it (guarantee immutability.)IHoconConfig
interfaceTo give us some idea of what this aforementioned
IHoconConfig
interface might look like, here's an example based on what we can extract from theAkka.Configuration.Config
class in Akka.NET v1.3.17:This prototype is incomplete as it doesn't offer types of
Config
access that is commonly used inside Akka.NET, such as iterating over theDictionary<string, HoconValue>
content of an unwrappedHoconObject
- that type of functionality will need to be incorporated into this interface too.Requirement: 100% of HOCON access that occurs inside Akka.NET should be doable through methods that have access to the
IHoconConfig
interface alone. In other words, we shouldn't have to castIHoconConfg
into anAkka.Configuration.Config
or other type of interfaceUsing
IHoconConfig
in PracticeHere's an example of how Akka.NET would eventually change to begin consuming stand-alone HOCON. The big sea change here is Akka.NET will be programmed to consume just the
IHoconConfig
interface, not any specific implementation of it. That's what will make the migration from one version to another feasible.First, we'd add a method overload that supports
IHoconConfig
:Once these overloads have been added, Akka.NET will be reading against the
IHoconConfig
interface instead of the concreteAkka.Configuration.Config
class. This will make it much easier to introduce stand-alone HOCON in the future, since it's just another implementation of the same interface with the same API. Only the underlying implementation is different, not the experience of consuming it.Development Plan
Here is how we intend to develop HOCON and integrate it back into Akka.NET over the course of the Akka.NET v1.4 lifecycle:
IHoconConfig
interface based onAkka.Configuration.Config
inside its own library,Hocon.Configuration.Abstractions
.IHoconConfig
interface coded at first (no parser, no implementation code,) reference it from Akka.NET, and haveAkka.Configuration.Config
implement it. Develop comprehensive behavioral test suite forIHoconConfig
it insideAkka.Configuration.Tests
. Ship that version of Akka.NET v1.4.IHoconConfig
overloads to common Akka.NET methods that take HOCON configuration objects:ActorSystem.Create
,Settings
,RouterConfig
, and others. Add overloads that accept anIHoconConfig
object and have theAkka.Configuration.Config
methods call down to theIHoconConfig
implementation. Existing test suite shouldn't return different results in the event that theIHoconConfig
implementation is complete and accurate. Release Akka.NET v1.4 version with these changes.IHoconConfig
interface.Akka.Configuration
calls inside Akka.NET with equivalent stand-alone HOCON library calls, but only after 100% of HOCON-consuming methods inside Akka.NET are programmed againstIHoconConfig
- i.e. Akka.NET should callHOCON.HoconConfigurationFactory.Default()
inside ofAkka.Config.ConfigurationFactory.Load()
.Akka.Configuration.Config
objects as arguments as[Obsolete]
and warn that these methods will be removed in a future major release of Akka.NET (1.5, 1.6, etc.)Akka.Configuration.Config
methods once the next major release of Akka.NET is shipped.HOCON Features
So what are the new features that should be added to stand-alone HOCON?
Microsoft.Extensions.Configuration
sources;Config
objects inside aMicrosoft.Extensions.Configuration
source object;The text was updated successfully, but these errors were encountered: