From feee275e228222c7914e8db393d620b4d7e51029 Mon Sep 17 00:00:00 2001 From: Alexandra Tran Carrillo <12214231+alexandratran@users.noreply.github.com> Date: Wed, 8 May 2024 11:36:33 -0700 Subject: [PATCH] Document Snaps network access (#1301) * Document Snaps network access * Update network-access.md Add one line about using a proxy if fetch is blocked by remote server. * add proxy resource --------- Co-authored-by: Christian Montoya --- docs/whats-new.md | 2 + snaps/features/network-access.md | 59 ++++++++++++++++++++++ snaps/features/non-evm-networks.md | 2 +- snaps/features/notifications.md | 2 +- snaps/features/signature-insights.md | 2 +- snaps/features/static-files.md | 2 +- snaps/how-to/debug-a-snap/common-issues.md | 2 +- snaps/index.mdx | 4 +- snaps/reference/permissions.md | 15 ------ 9 files changed, 68 insertions(+), 22 deletions(-) create mode 100644 snaps/features/network-access.md diff --git a/docs/whats-new.md b/docs/whats-new.md index 3c98bd7da5e..f48fc44169f 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -11,6 +11,8 @@ of the [MetaMask developer page](https://metamask.io/developer/). ## May 2024 +- Documented [Snaps network access](/snaps/features/network-access). + ([#1301](https://github.com/MetaMask/metamask-docs/pull/1301)) - Documented [provider API methods for removing event listeners](/wallet/reference/provider-api/#remove-event-listeners). ([#1288](https://github.com/MetaMask/metamask-docs/pull/1288)) diff --git a/snaps/features/network-access.md b/snaps/features/network-access.md new file mode 100644 index 00000000000..5d8de6de599 --- /dev/null +++ b/snaps/features/network-access.md @@ -0,0 +1,59 @@ +--- +description: Access the internet using the fetch function. +sidebar_position: 8 +--- + +# Network access + +You can access the internet from a Snap using the global `fetch` API. + +## Steps + +### 1. Request permission to access the internet + +Request the [`endowment:network-access`](../reference/permissions.md#endowmentnetwork-access) permission, +which exposes the global `fetch` API to the Snaps execution environment. +Add the following to your Snap's manifest file: + +```json title="snap.manifest.json" +"initialPermissions": { + "endowment:network-access": {} +} +``` + +### 2. Use the `fetch` function + +You can now use the `fetch` function to access the internet. +The following example fetches a JSON file from the provided URL. + +```ts title="index.ts" +async function getJson(url: string) { + const response = await fetch(url); + return await response.json(); +} +``` + +:::info Same-origin policy and CORS +`fetch` requests in a Snap are bound by the browser's +[same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#cross-origin_network_access). +Since Snap code is executed in an iframe with the `sandbox` property, the browser sends an `Origin` +header with the value `null` with outgoing requests. +For the Snap to be able to read the response, the server must send an +[`Access-Control-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) CORS header +with the value `*` or `null` in the response. +Otherwise, you might need to +[set up a proxy](https://stackoverflow.com/questions/43871637/no-access-control-allow-origin-header-is-present-on-the-requested-resource-whe/43881141#43881141). +::: + +:::caution +`XMLHttpRequest` isn't available in Snaps, and you should replace it with `fetch`. +If your dependencies use `XMLHttpRequest`, you can +[patch it away](../how-to/debug-a-snap/common-issues.md#patch-the-use-of-xmlhttprequest). +::: + +## Example + +See the [`@metamask/network-access-example-snap`](https://github.com/MetaMask/snaps/tree/main/packages/examples/packages/network-access) +package for a full example of accessing the internet from a Snap. +This example exposes a [custom JSON-RPC API](../learn/about-snaps/apis.md#custom-json-rpc-apis) for +dapps to call the `fetch` function from a Snap. diff --git a/snaps/features/non-evm-networks.md b/snaps/features/non-evm-networks.md index c4ee3f3bb6f..42974429994 100644 --- a/snaps/features/non-evm-networks.md +++ b/snaps/features/non-evm-networks.md @@ -1,6 +1,6 @@ --- description: Manage users' non-EVM accounts and assets. -sidebar_position: 8 +sidebar_position: 9 --- # Non-EVM networks diff --git a/snaps/features/notifications.md b/snaps/features/notifications.md index 9b555c7936c..aa76896b4b5 100644 --- a/snaps/features/notifications.md +++ b/snaps/features/notifications.md @@ -1,6 +1,6 @@ --- description: Notify users directly in MetaMask, or natively in their OS. -sidebar_position: 9 +sidebar_position: 10 --- # Notifications diff --git a/snaps/features/signature-insights.md b/snaps/features/signature-insights.md index 32b7e556547..e60a988b951 100644 --- a/snaps/features/signature-insights.md +++ b/snaps/features/signature-insights.md @@ -1,6 +1,6 @@ --- description: Provide insights to your users in MetaMask's signature confirmation flow. -sidebar_position: 10 +sidebar_position: 11 sidebar_custom_props: flask_only: true --- diff --git a/snaps/features/static-files.md b/snaps/features/static-files.md index 3641a87d6ac..f7ad2db29dc 100644 --- a/snaps/features/static-files.md +++ b/snaps/features/static-files.md @@ -1,6 +1,6 @@ --- description: Include and retrieve static files in the Snap bundle. -sidebar_position: 11 +sidebar_position: 12 --- # Static files diff --git a/snaps/how-to/debug-a-snap/common-issues.md b/snaps/how-to/debug-a-snap/common-issues.md index 327de583a81..3603730abc9 100644 --- a/snaps/how-to/debug-a-snap/common-issues.md +++ b/snaps/how-to/debug-a-snap/common-issues.md @@ -96,7 +96,7 @@ Now you can make changes to your dependencies inside `node_modules` and run This creates a `.patch` file containing your dependency patch. These patches can be committed to your Git repository and are replayed when you re-install your dependencies. -### Patch the use of XMLHttpRequest +### Patch the use of `XMLHttpRequest` The `XMLHttpRequest` API is not exposed in the Snaps execution environment and won't be in the future. Because of this, you may run into issues with dependencies in your dependency tree attempting to diff --git a/snaps/index.mdx b/snaps/index.mdx index e4877d521cb..0fd8b2edc2b 100644 --- a/snaps/index.mdx +++ b/snaps/index.mdx @@ -74,9 +74,9 @@ The following Snaps features are available in the stable version of MetaMask: }, { icon: require("./assets/features/network.png").default, - href: "reference/permissions#endowmentnetwork-access", + href: "features/network-access", title: "Network access", - description: <>Make API calls using fetch(). + description: <>Access the internet using the fetch function. }, { icon: require("./assets/features/locale.png").default, diff --git a/snaps/reference/permissions.md b/snaps/reference/permissions.md index 9066621d003..71c2738183d 100644 --- a/snaps/reference/permissions.md +++ b/snaps/reference/permissions.md @@ -199,12 +199,6 @@ domain resolution is happening on Ethereum Mainnet. To access the internet, a Snap must request the `endowment:network-access` permission. This permission exposes the global `fetch` API to the Snaps execution environment. -:::caution -`XMLHttpRequest` isn't available in Snaps, and you should replace it with `fetch`. -If your dependencies use `XMLHttpRequest`, you can -[patch it away](../how-to/debug-a-snap/common-issues.md#patch-the-use-of-xmlhttprequest). -::: - Specify this permission in the manifest file as follows: ```json title="snap.manifest.json" @@ -213,15 +207,6 @@ Specify this permission in the manifest file as follows: } ``` -#### Same-origin policy and CORS - -`fetch()` requests in a Snap are bound by the browser's [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#cross-origin_network_access). -Since Snap code is executed in an iframe with the `sandbox` property, the browser sends an `Origin` -header with the value `null` with outgoing requests. -For the Snap to be able to read the response, the server must send an -[`Access-Control-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) CORS header -with the value `*` or `null` in the response. - ### `endowment:rpc` To handle arbitrary JSON-RPC requests, a Snap must request the `endowment:rpc` permission.