@@ -13,44 +13,44 @@ overview of the components that make up the Shorebird system.
1313
1414## Lifetime of a Shorebird Update
1515
16- This assumes the developer already has installed Shorebird and has a working Flutter
17- project, as covered in the [ Getting Started] ( / ) guide.
16+ This assumes the developer already has installed Shorebird and has a working
17+ Flutter project, as covered in the [ Getting Started] ( / ) guide.
1818
1919` shorebird init ` tells Shorebird servers to create a new "App" entry associated
2020with your account as well as writes the resulting app_id to ` shorebird.yaml ` in
2121your project.
2222
23- ` shorebird release ` builds your app using ` flutter build ` and then uploads
24- the resulting binary to a private Google Cloud Storage bucket. The command
25- also creates a "release" record in our database that associates the app_id
26- with the release version.
23+ ` shorebird release ` builds your app using ` flutter build ` and then uploads the
24+ resulting binary to a private Google Cloud Storage bucket. The command also
25+ creates a "release" record in our database that associates the app_id with the
26+ release version.
2727
2828` shorebird preview ` can be used to download and run any of these privately
2929stored release binaries on your local device.
3030
31- Developers then typically take the resulting .aab or .ipa and distribute it
32- to their users, typically via the Play Store or App Store.
31+ Developers then typically take the resulting .aab or .ipa and distribute it to
32+ their users, typically via the Play Store or App Store.
3333
34- At some point later, developers use ` shorebird patch ` to build a new version
35- of their app. ` shorebird patch ` then downloads the previous release binary
34+ At some point later, developers use ` shorebird patch ` to build a new version of
35+ their app. ` shorebird patch ` then downloads the previous release binary
3636associated with that app_id and version number (patches use the same version
37- number as the release they are patching) and then builds a "patch diff" from
38- the combined release and patch binaries. This "patch diff" is then uploaded
39- to a public Google Cloud Storage bucket where it will be served to devices
40- requesting an update with the corresponding app_id and release version.
37+ number as the release they are patching) and then builds a "patch diff" from the
38+ combined release and patch binaries. This "patch diff" is then uploaded to a
39+ public Google Cloud Storage bucket where it will be served to devices requesting
40+ an update with the corresponding app_id and release version.
4141
4242` shorebird patch ` also creates a record in our database that associates the
4343patch with the app_id and release version and alerts our "patch check" servers
44- that a new patch is available. Patches can optionally be "staged" when
45- uploaded. They will then not appear in patch checks until the patch "channel"
46- is set to "stable" by the developer in the Shorebird Console.
44+ that a new patch is available. Patches can optionally be "staged" when uploaded.
45+ They will then not appear in patch checks until the patch "channel" is set to
46+ "stable" by the developer in the Shorebird Console.
4747
4848Release binaries which were built with Shorebird contain Shorebird's updater
49- library. By default, the updater library will check for patches every time
50- the app is started. This is done via a background thread to not slow down
51- launch. The updater code makes a single request to our "patch check" servers
52- which are again Google Cloud Run instances. The "patch check" servers
53- respond with the URL of the patch diff if one is available.
49+ library. By default, the updater library will check for patches every time the
50+ app is started. This is done via a background thread to not slow down launch.
51+ The updater code makes a single request to our "patch check" servers which are
52+ again Google Cloud Run instances. The "patch check" servers respond with the URL
53+ of the patch diff if one is available.
5454
5555A typical patch check is made via https, and contains:
5656
@@ -78,24 +78,24 @@ A patch response contains:
7878}
7979```
8080
81- The code to do these checks is open source as part of the [ Shorebird Updater
82- library] ( https://github.com/shorebirdtech/updater/blob/main/library ) and may
83- change from what is documented above:
81+ The code to do these checks is open source as part of the
82+ [ Shorebird Updater library] ( https://github.com/shorebirdtech/updater/blob/main/library )
83+ and may change from what is documented above:
8484https://github.com/shorebirdtech/updater/blob/main/library/src/network.rs
8585
86- The updater library then downloads the patch diff and applies it to the
87- release binary. The patch diff is a binary diff. The updater library
88- also checks the hash of the patch diff to confirm download integrity.
86+ The updater library then downloads the patch diff and applies it to the release
87+ binary. The patch diff is a binary diff. The updater library also checks the
88+ hash of the patch diff to confirm download integrity.
8989
9090The hash is not meant to be a security feature, but rather a way to detect
91- errors in the patch diff. A common error we see is that developers `shorebird
92- release` with one source and then actually build and release a different binary,
93- resulting then in invalid patches. This hash helps detect such errors. We
94- currently do not sign patches, but plan to add that capability in the near
95- future.
91+ errors in the patch diff. A common error we see is that developers
92+ ` shorebird release` with one source and then actually build and release a
93+ different binary, resulting then in invalid patches. This hash helps detect such
94+ errors. We currently do not sign patches, but plan to add that capability in the
95+ near future.
9696
97- The modified Flutter engine also reports successful or failed launch of
98- a patch back to our servers the next time it makes a patch check.
97+ The modified Flutter engine also reports successful or failed launch of a patch
98+ back to our servers the next time it makes a patch check.
9999
100100A patch event contains:
101101
@@ -122,13 +122,15 @@ This is to prevent a bad patch from causing a crash loop on the device.
122122
123123Shorebird consists of 3 major parts:
124124
125- 1 . The ` Shorebird CLI ` tool that you use to build and deploy your app from the command line.
125+ 1 . The ` Shorebird CLI ` tool that you use to build and deploy your app from the
126+ command line.
1261271 . A modified Flutter engine that is include in your app.
1271281 . Our public-cloud infrastructure which hosts your app's updates.
128129
129130### The ` Shorebird CLI `
130131
131- The [ ` shorebird_cli ` ] ( https://github.com/shorebirdtech/shorebird/tree/main/packages/shorebird_cli )
132+ The
133+ [ ` shorebird_cli ` ] ( https://github.com/shorebirdtech/shorebird/tree/main/packages/shorebird_cli )
132134commands are documented on this site. Most of the build logic is just wrapping
133135the ` flutter ` tool and it also adds a few commands to interface with Shorebird's
134136servers.
@@ -142,18 +144,19 @@ We had to fork 4 Flutter and Dart repositories to make Shorebird work:
142144
143145#### ` flutter/buildroot ` "The Buildroot"
144146
145- The [ ` flutter/buildroot ` ] ( https://github.com/flutter/buildroot ) repo contains the build scripts that are used to build the
146- Flutter engine for various platforms. It's separate from ` flutter/engine ` in
147- order to share code and configuration with the Fuchsia build system.
147+ The [ ` flutter/buildroot ` ] ( https://github.com/flutter/buildroot ) repo contains
148+ the build scripts that are used to build the Flutter engine for various
149+ platforms. It's separate from ` flutter/engine ` in order to share code and
150+ configuration with the Fuchsia build system.
148151
149152We forked this repository to make several small modifications:
150153
1511541 . Expose our updater symbols from the Flutter engine up to
152155 ` package:shorebird_code_push `
153156
154- 1 . Include ` libunwind ` since the [ Shorebird
155- Updater] ( https://github.com/shorebirdtech/updater ) (Rust) code requires it
156- for backtraces.
157+ 1 . Include ` libunwind ` since the
158+ [ Shorebird Updater] ( https://github.com/shorebirdtech/updater ) (Rust) code
159+ requires it for backtraces.
157160
158161The [ Shorebird Updater] ( https://github.com/shorebirdtech/updater ) is a Rust
159162library which is linked into the Flutter engine via a static library
@@ -164,9 +167,8 @@ static libraries, and because we need to be able to expose the `shorebird\_\*`
164167symbols from ` libupdater.a ` to the Dart code, we made one change to ` buildroot `
165168and then a second change to the ` engine ` to place the symbols on the allow-list.
166169
167- :::note
168- You can see our buildroot changes on GitHub by
169- comparing our trunk to the upstream buildroot, e.g. master:
170+ :::note You can see our buildroot changes on GitHub by comparing our trunk to
171+ the upstream buildroot, e.g. master:
170172https://github.com/flutter/buildroot/compare/master...shorebirdtech:buildroot:shorebird/dev
171173:::
172174
@@ -180,24 +182,24 @@ We forked this code to add the
180182[ Shorebird Updater] ( https://github.com/shorebirdtech/updater ) , which lets the
181183Flutter engine load new code from Shorebird's servers.
182184
183- :::note
184- Our Flutter Engine fork is public. You can see our engine changes on GitHub by
185- comparing our trunk to the upstream Flutter engine, e.g. for 3.22.0:
185+ :::note Our Flutter Engine fork is public. You can see our engine changes on
186+ GitHub by comparing our trunk to the upstream Flutter engine, e.g. for 3.22.0:
186187https://github.com/flutter/engine/compare/3.22.0...shorebirdtech:engine:shorebird/dev
187188:::
188189
189190#### ` flutter/flutter ` "The Flutter Framework"
190191
191- The [ ` flutter/flutter ` ] ( https://github.com/flutter/flutter/ ) repo contains the Dart code that runs on the device as well
192- as the ` flutter ` tool that is used to build and run Flutter apps.
192+ The [ ` flutter/flutter ` ] ( https://github.com/flutter/flutter/ ) repo contains the
193+ Dart code that runs on the device as well as the ` flutter ` tool that is used to
194+ build and run Flutter apps.
193195
194196We forked this code to be able to deliver our modified Flutter engine to change
195197the version of the engine that the ` flutter ` tool uses and to include the
196198` shorebird.yaml ` configuration as part of the asset bundle.
197199
198- :::note
199- Our Flutter Framework fork is public. You can see our engine changes on GitHub
200- by comparing our trunk to the upstream Flutter Framework, e.g. for stable:
200+ :::note Our Flutter Framework fork is public. You can see our engine changes on
201+ GitHub by comparing our trunk to the upstream Flutter Framework, e.g. for
202+ stable:
201203https://github.com/flutter/flutter/compare/stable...shorebirdtech:flutter:shorebird/dev
202204:::
203205
@@ -209,11 +211,9 @@ SDK, including the VM, dart2js, core libraries, and more.
209211We forked this code in order to teach Dart how to run modified (patched) code in
210212an interpreter while being able to run all unmodified code on the CPU.
211213
212- :::note
213- Our Dart SDK fork is private currently. It will likely be public in the future
214- and we will work to upstream many our changes as the team grows and the product
215- matures.
216- :::
214+ :::note Our Dart SDK fork is private currently. It will likely be public in the
215+ future and we will work to upstream many our changes as the team grows and the
216+ product matures. :::
217217
218218#### Installing a Forked Flutter
219219
@@ -232,18 +232,19 @@ change the version of the engine in the `flutter` tool. Second is we pass
232232` FLUTTER_STORAGE_BASE_URL ` set to ` download.shorebird.dev ` (instead of
233233` download.flutter.io ` ) when calling our vended copy of the ` flutter ` tool.
234234
235- Currently this means ` shorebird ` will not work in an environment where the
236- user needs to use ` FLUTTER_STORAGE_BASE_URL ` to download Flutter artifacts
237- from a private mirror (e.g. a corporate network or China).
235+ Currently this means ` shorebird ` will not work in an environment where the user
236+ needs to use ` FLUTTER_STORAGE_BASE_URL ` to download Flutter artifacts from a
237+ private mirror (e.g. a corporate network or China).
238238https://github.com/shorebirdtech/shorebird/issues/237
239239
240240#### Serving Forked Binaries
241241
242- We also use a custom server to handle requests from ` flutter ` for our
243- modified engine. The source for that server is here:
242+ We also use a custom server to handle requests from ` flutter ` for our modified
243+ engine. The source for that server is here:
244244https://github.com/shorebirdtech/shorebird/tree/main/packages/artifact_proxy
245245
246- The artifact proxy is hosted at https://download.shorebird.dev via Google Cloud Run.
246+ The artifact proxy is hosted at https://download.shorebird.dev via Google Cloud
247+ Run.
247248
248249This proxy knows how to serve the modified binaries from our Google Storage
249250bucket, as well as how to forward along requests to Google's Flutter storage
@@ -259,9 +260,9 @@ app's updates. It's a set of services that handle the following:
259260- Patch binary (public) storage and serving (via global CDN)
260261- Patch check requests (via Google Cloud Run)
261262
262- We also provide a web-based console for developers to manage their apps and
263- view analytics as well as the underlying database that powers the patch checks
264- and console.
263+ We also provide a web-based console for developers to manage their apps and view
264+ analytics as well as the underlying database that powers the patch checks and
265+ console.
265266
266267Currently all of our infrastructure is hosted on Google Cloud Platform although
267268we will likely expand to other cloud providers over time. If we do, we will
0 commit comments