From 287619d233109ff07bc8f6ce875a775af22f3ef2 Mon Sep 17 00:00:00 2001 From: Alexandros Tzimas Date: Wed, 15 Jan 2025 22:25:07 +0200 Subject: [PATCH] chore: update the walrus sites docs to align with new Testnet deployment (#203) --- docs/walrus-sites/authentication.md | 2 +- docs/walrus-sites/intro.md | 4 +- docs/walrus-sites/overview.md | 15 +++++-- docs/walrus-sites/restrictions.md | 62 ++++++++++++++++----------- docs/walrus-sites/tutorial-publish.md | 2 +- 5 files changed, 53 insertions(+), 32 deletions(-) diff --git a/docs/walrus-sites/authentication.md b/docs/walrus-sites/authentication.md index 7b3516b6..c1dea561 100644 --- a/docs/walrus-sites/authentication.md +++ b/docs/walrus-sites/authentication.md @@ -32,7 +32,7 @@ has been fetched) did not tamper with the contents of the blob. Here, the portal provider is only trusted to provide the correct service worker code to the user. The user's browser will then perform the fetching and authentication. The guarantees are therefore -the same as with the remote server-site portal, with the addition that the user can inspect the code +the same as with the remote server-side portal, with the addition that the user can inspect the code returned by the portal provider and verify its integrity (e.g., by comparing it the hash of the service worker code to one that is known to be correct). diff --git a/docs/walrus-sites/intro.md b/docs/walrus-sites/intro.md index 201251bf..506f4da2 100644 --- a/docs/walrus-sites/intro.md +++ b/docs/walrus-sites/intro.md @@ -33,8 +33,8 @@ You can check out the mint page at . This site is browser through the Walrus Site *portal* . While the portal's operation is explained in a [later section](./portal.md), consider for now that there can be many portals (hosted by whoever wants to have their own, and even on `localhost`). Further, the only function of the -portal is to provide the browser with some code (specifically, a service worker) that allows it to -fetch the Walrus Site from Sui and Walrus. +portal is to retrieve the metadata (from Sui) and the resource files (from Walrus) that constitute +the site. If you have a Sui wallet with some Testnet SUI, you can try and "mint a new Flatlander" from the site. This creates an NFT from the collection and shows you two links: one to the explorer, and one diff --git a/docs/walrus-sites/overview.md b/docs/walrus-sites/overview.md index f4ac6790..94107e36 100644 --- a/docs/walrus-sites/overview.md +++ b/docs/walrus-sites/overview.md @@ -100,9 +100,10 @@ Base36 was chosen for two reasons, forced by the subdomain standards: As mentioned before, we provide two types of portals to browse Walrus Sites: - The server-side portal, which is a server that resolves a Walrus Site, returning it to the - browser. The server-side portal is hosted at . -- The service-worker portal, which is a service worker that is installed in the browser and resolves - a Walrus Site. The service-worker portal is hosted at . + browser. The server-side portal is hosted at . +- The service-worker portal, which is a service worker that is installed in the browser and + resolves a Walrus Site. The service-worker portal is no longer hosted at a specific domain, but + the code is still maintained so that it can be used by anyone. We now describe the resolution process of a Walrus Site in the browser using the service-worker portal as an example. @@ -135,6 +136,14 @@ worker approach. The steps below all reference the following figure: These steps are executed for all resources the browser may query thereafter (for example, if `/index.html` points to `assets/cat.png`). +```admonish tip title="Server side approach" +The server-side portal works similarly, but the resolution is performed by the server. Meaning that +the server will resolve the SuiNS name, fetch the dynamic fields, and return the resources to the +browser, without anything else happening on the user's side. So the steps 2-6 are no longer +relevant, and 7-10 are performed by the server. The resulting resources are transmitted to the +browser in a standard HTTP response. +``` + ## The site builder To facilitate the creation of Walrus Sites, we provide the "site builder" tool. The site builder diff --git a/docs/walrus-sites/restrictions.md b/docs/walrus-sites/restrictions.md index 2f09082d..1fcac080 100644 --- a/docs/walrus-sites/restrictions.md +++ b/docs/walrus-sites/restrictions.md @@ -22,43 +22,55 @@ does not result in an infinite loading loop. Different portals can set this limit as they desire. The limit for the portal hosted at has a maximum redirect depth of 3. -## Service workers are not available +## Service-worker portal limitations -Walrus Sites leverage service workers in the clients' browsers to perform essential operations: +The following limitations only apply to portals based on service workers. + +``` admonish tip +If you need to support any of the features listed below, you should use a server-side portal. +``` + +### Service-worker portals, can't serve sites based on service workers + +Service-worker portals leverage service workers in the clients' browsers to perform essential +operations: 1. reading the site metadata from Sui; 1. fetching the page content from Walrus; and 1. serving the content to the browser. -Therefore, a site deployed on Walrus Sites cannot use service workers itself. Installing a service -worker from within a Walrus Site will result in a dysfunctional site and a poor experience for the -user. +Therefore, a site accessed by a service-worker portal cannot use service workers itself. i.e. +you can't "stack" service workers! Installing a service worker from within a Walrus Site will +result in a dysfunctional site and a poor experience for the user. -```admonish note -This limitation only applies to portal based on service workers. A web portal will not -have this limitation. -``` +### iOS Sui mobile wallets do not work with the service-worker portal -## iOS Sui mobile wallets do not work with the service-worker portal +```admonish warning +This limitation **only applies to portal based on service workers**. If you need to access sites +that support this feature, you should use a server-side portal. +``` Service workers cannot be loaded inside an in-app browser on iOS, because of a limitation of the -WebKit engine. As a consequence, Walrus Sites cannot be used within Sui-compatible wallet apps on -iOS. Therefore, Sui wallets cannot currently be used on a service-worker portal on iOS. Note, -however, that *browsing* a Walrus Site is still possible on iOS through any browser. - -To provide a seamless experience for iOS users (and other users on browsers that do not support -service workers), we implemented a redirect to a server-side portal (). Whenever -a user on an iOS wallet browses a Walrus Site, the redirect will automatically take them to the -`.blob.store` server-side portal. This way, the user can still use the wallet. - -```admonish note -This limitation only applies to portals based on service workers. A web portal will not -have this limitation. +WebKit engine. As a consequence, Walrus Sites that are accessed through a service worker portal +cannot be used within Sui-compatible wallet apps on iOS. Therefore, Sui wallets cannot currently +be used on a service-worker portal on iOS. Note, however, that *browsing* a Walrus Site is still +possible on iOS through any browser. + +Given that you decided to use a service-worker portal as your main point of access to your sites, +to provide a seamless experience for iOS users (and other users on browsers that do not support +service workers), it is recommended to redirect to a server-side portal (). +Whenever a user on an iOS wallet browses a Walrus Site, the redirect will automatically take them +to the `.walrus.site` server-side portal. This way, the user can still use the wallet. + +### Service worker portals do not support progressive web apps (PWAs) + +```admonish warning +This limitation **only applies to portal based on service workers**. If you need to access sites +that support this feature, you should use a server-side portal. ``` -## No support for progressive web apps (PWAs) - -With the current design, Walrus Sites cannot be used for progressive web apps (PWAs). +With the current design, service-worker portals cannot be used to access progressive web apps +(PWAs). Two characteristics of the service-worker portal prevent support for PWAs: diff --git a/docs/walrus-sites/tutorial-publish.md b/docs/walrus-sites/tutorial-publish.md index 63505ae5..eec28190 100644 --- a/docs/walrus-sites/tutorial-publish.md +++ b/docs/walrus-sites/tutorial-publish.md @@ -14,7 +14,7 @@ repository that contains multiple kinds of sites that you can use for reference. For simplicity, we will start by publishing the most frugal of the sites, the `walrus-snake` game. -First, clone the repository of examples: +First, clone the repository of the examples: ``` sh git clone https://github.com/MystenLabs/example-walrus-sites.git && cd walrus-snake/