From e1c1bb788c6d7b1d9ca56a3d9d50d63137a06c7e Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Fri, 19 May 2023 16:22:20 -0700 Subject: [PATCH] Add a blog post about the new Embedded Protocol proposal (#729) --- source/blog/037-rfc-embedded-protocol-2.md | 76 ++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 source/blog/037-rfc-embedded-protocol-2.md diff --git a/source/blog/037-rfc-embedded-protocol-2.md b/source/blog/037-rfc-embedded-protocol-2.md new file mode 100644 index 0000000..b5a2527 --- /dev/null +++ b/source/blog/037-rfc-embedded-protocol-2.md @@ -0,0 +1,76 @@ +--- +title: "Request for Comments: New Embedded Protocol" +author: Natalie Weizenbaum +date: 2023-05-19 16:00 PST +--- + +If you're not an author of a host package for the Embedded Sass Protocol, you +can skip this blog post—although if you're a big enough nerd, you may find it +interesting regardless! + +We're planning to make a number of breaking changes to the Embedded Sass +Protocol, and we want your feedback before we lock in the new way of doing +things. We intend to make a number of breaking changes all at once to keep the +total number of disruptions to a minimum. + +We're planning two major breaking changes: + +1. The Dart Sass embedded host will no longer be released as a separate + executable. It will now be bundled into the main Dart Sass executable, + accessible by running `sass --embedded`. + +2. Every packet in the embedded protocol now includes a compilation ID as part + of the packet structure, rather than declaring it in the protocol buffer + definitions. + +We're using this opportunity to also introduce three much smaller breaking +changes: + +1. The specification for the embedded protocol and the protocol buffer + definition have been moved to [the Sass language repository] so that they can + be updated at the same time as changes to the language and the JS API. + + [the Sass language repository]: https://github.com/sass/sass/blob/main/spec/embedded-protocol.md + +2. The embedded protocol now explicitly declares optional fields using the + protocol buffers language feature. This means that "default values" for + various fields are no longer considered to be unset. + +3. The `CompilationSuccess.loaded_urls` field has been moved to + `CompilationResult.loaded_urls` so that it's available even when a + compilation fails. This allows watcher implementations to know which files to + watch to redo a failed compilation. + +The repository-organization changes have already been made, but the changes to +the protocol itself are fully documented [in a proposal in the language +repository]. + +[in a proposal in the language repository]: https://github.com/sass/sass/blob/main/proposal/embedded-protocol-2.md + +## Combining Executables + +The primary benefit of folding Embedded Dart Sass into the main Dart Sass +executable is to provide embedded hosts an easy way to expose the standard Dart +Sass command-line API to users. Now every user who installs any embedded host +will have the full Dart Sass executable available to them at native Dart VM +speeds. + +This also helps simplify the Sass team's organization by reducing the number of +separate repositories and release processes we need to manage. + +## Wire-Level Compilation ID + +We're pulling the compilation ID out to the protocol level in order to provide +better concurrency, particularly on the side of the embedded compiler. Sass +compilations done by the embedded compiler don't share any state between one +another, which means that they could in theory be run in totally separate worker +threads. However, with the embedded protocol as it exists today, directing each +message to the correct worker thread requires parsing the entire message on the +main thread to determine which compilation it belongs to, then parsing it +_again_ in the worker thread to actually handle it. + +Making the compilation ID part of the protocol itself solves this issue. Each +endpoint can read the ID, look up the worker thread that's handling the +compilation, and pass the message on to that thread without parsing the rest of +the message. This makes concurrency both easier and more efficient, which will +help ensure that large compilations happen as fast as possible.