From fee8f79c5f9cde0671f605a80c20df0eefca8da9 Mon Sep 17 00:00:00 2001 From: Sarah Jamie Lewis Date: Thu, 2 Mar 2023 15:53:37 -0800 Subject: [PATCH] Erinn Comments --- ...03-03-autobindings-optional-experiments.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/blog/2023-03-03-autobindings-optional-experiments.md b/blog/2023-03-03-autobindings-optional-experiments.md index 7f564cbc..72979eee 100644 --- a/blog/2023-03-03-autobindings-optional-experiments.md +++ b/blog/2023-03-03-autobindings-optional-experiments.md @@ -22,14 +22,14 @@ authors: An application-level experiment consists of: -1. A set of top-level APIs e.g. `CreateServer`, `LoadServer`, `DeleteServer` - these are the APIs that we want to expose to calling applications. -2. An encapsulating structure for the set of APIs e.g. `ServersFunctionality` - it is much easy to manage a cohesive set of functionality if it is wrapped up in a single entity. -3. A global variable that exists at the top level of libCwtch e.g. `var serverExperiment *servers.ServersFunctionality servers` - our single pointer to the underlying functionality. -4. A set of management-related APIs e.g. `Init`, `UpdateSettings`, `OnACNEvent` - in the case of the server hosting experiment we need to perform specific actions when we start up (e.g. loading unencrypted hosted servers), and when settings are -changes (e.g. if the server hosting experiment is disabled we need to tear down all active servers). +1. A set of top-level APIs, e.g. `CreateServer`, `LoadServer`, `DeleteServer` - these are the APIs that we want to expose to calling applications. +2. An encapsulating structure for the set of APIs, e.g. `ServersFunctionality` - it is much easy to manage a cohesive set of functionality if it is wrapped up in a single entity. +3. A global variable that exists at the top level of libCwtch, e.g. `var serverExperiment *servers.ServersFunctionality servers` - our single pointer to the underlying functionality. +4. A set of management-related APIs, e.g. `Init`, `UpdateSettings`, `OnACNEvent` - in the case of the server hosting experiment we need to perform specific actions when we start up (e.g. loading unencrypted hosted servers), and when settings are +changed (e.g. if the server hosting experiment is disabled we need to tear down all active servers). 5. Management code within `_startCwtch` and `_reconnectCwtch` that calls the management APIs on the global variable. -From a code generation perspective we already have most of the functionality is place to support (1) - the one major difference being that we need to wrap function calls on the global variable assoicated with the experiment, instead +From a code generation perspective we already have most of the functionality is place to support (1) - the one major difference being that we need to wrap function calls on the global variable associated with the experiment, instead of on `application` or a specific `profile`. Most of the effort required to support optional experiments was focused on optionally weaving experiment management code within the template. @@ -37,7 +37,7 @@ Most of the effort required to support optional experiments was focused on optio ### New Required Management APIs To achieve this weaving, we now require application-level experiments to implement an `EventHandlerInterface` interface and expose itself via an -initialize constructor `Init(acn, appDir) -> EventHandlerInterface`, and `Enable(app, acn)` +initialize constructor `Init(acn, appDir) -> EventHandlerInterface`, and `Enable(app, acn)`. For now this interface is rather minimal, and has been mapped almost exactly to how the server hosting experiment already worked. If, or when, a new application experiment is required we will likely revisit this interface. @@ -47,12 +47,12 @@ We can then generate, and optionally include blocks of code like: eventHandler.AddModule() .Enable(application, &globalACN) -And place them at specific points in the code. `EventHandle` has also been extended to maintain a collection of `modules` so that it can +and place them at specific points in the code. `EventHandler` has also been extended to maintain a collection of `modules` so that it can pass on interesting events. ### Adding Support for Application Experiments in the Spec File -We have introduced a new `!` operator which can be used to gat which APIs behind a configured experiment. Along with a new +We have introduced a new `!` operator which can be used to gate APIs behind a configured experiment. Along with a new templating option `exp` which will call the function on the configured experiment, and `global` to allow the setting up of a global functionality within the library. @@ -73,12 +73,12 @@ of a global functionality within the library. Without any arguments provided `generate-bindings` will not generate code for any experiments. - In order to determine what experimental code to generate, `generate-bindings` now interprets arguments as enabled compile time experiments e.g. `generate-bindings serverExperiment` will turn on + In order to determine what experimental code to generate, `generate-bindings` now interprets arguments as enabled compile time experiments, e.g. `generate-bindings serverExperiment` will turn on generation of server hosting code, per the spec file above. ### Cwtch UI Integration -The UI, and other downstream applications, can now check for support for server hosting by simply checking if the loaded library provides the expected symbols e.g. `c_LoadServers` - if it doesn't then the UI is safe to assume the +The UI, and other downstream applications, can now check for support for server hosting by simply checking if the loaded library provides the expected symbols, e.g. `c_LoadServers` - if it doesn't then the UI is safe to assume the feature is not available.
@@ -90,15 +90,15 @@ feature is not available. ## Nightlies & Next Steps -We are now publishing [nightlies](https://build.openprivacy.ca/files/libCwtch-autobindings-v0.0.1/) of autobinding derived libCwtch-go, along with reproducible [Repliqate scripts](https://git.openprivacy.ca/cwtch.im/repliqate-scripts/src/branch/main/cwtch-autobindings-v0.0.1) +We are now publishing [nightlies](https://build.openprivacy.ca/files/libCwtch-autobindings-v0.0.1/) of autobinding derived libCwtch-go, along with [Repliqate scripts](https://git.openprivacy.ca/cwtch.im/repliqate-scripts/src/branch/main/cwtch-autobindings-v0.0.1) for reproducibility. With application experiments supported, this phase of autobindings comes to a close. The immediate next steps involve extensive testing and release candidates proving out the new bindings to ensure that no bugs have been introduced -in the migration from libCwtch-go. These candidates will form the base for Cwtch Beta 1.11. +in the migration from libCwtch-go. These candidates will form the basis for Cwtch Beta 1.11. -However there is still more work to do, and we expect to make progress on a few areas over the next few months, including: +However, there is still more work to do, and we expect to make progress on a few areas over the next few months, including: -* **Dart Library generation**: since we now have a formal description of the bindings interface, we can move ahead with also autogenerating the [Dart-side](https://git.openprivacy.ca/cwtch.im/cwtch-ui/src/branch/trunk/lib/cwtch) of the bindings interface, giving a boost to UI integration of new features, and allowing us to generate tailored versions of the UI interface e.g. one compiled without experiment support. We can also extend the same logic to other downstream interfaces e.g. [libcwtch-rs](https://git.openprivacy.ca/cwtch.im/libcwtch-rs) - * **Documentation generation**: another benefit of a formal description of the bindings interface, we can easily generate documentation compatible with [docs.cwtch.im](https://cwtch.im). +* **Dart Library generation**: since we now have a formal description of the bindings interface, we can move ahead with also autogenerating the [Dart side](https://git.openprivacy.ca/cwtch.im/cwtch-ui/src/branch/trunk/lib/cwtch) of the bindings interface, giving a boost to UI integration of new features, and allowing us to generate tailored versions of the UI interface, e.g. one compiled without experiment support. We can also extend the same logic to other downstream interfaces, e.g. [libcwtch-rs](https://git.openprivacy.ca/cwtch.im/libcwtch-rs). + * **Documentation generation**: as another benefit of a formal description of the bindings interface, we can easily generate documentation compatible with [docs.cwtch.im](https://cwtch.im). ## Help us go further!