Difference between revisions of "Boundary Nodes"

Latest revision as of 08:58, 25 January 2024

The boundary nodes are the gateway to the Internet Computer (IC), and allow users to seamlessly access the canister smart contracts running on it. The following figure shows how the boundary nodes form the edge of the IC and all accesses to the IC have to go through one of the boundary nodes.

Boundary Node Internals

At a closer look, boundary nodes consist of two parts: the API node, which provides an endpoint for API canister calls, and the HTTP gateway, which provides an HTTP endpoint for users to access the canisters hosted on the IC with their stock browser.

API Node

The API endpoint resides at icp-api.io/api/v2 and is specified in the IC’s Interface Specification.

Whenever a boundary node receives an API canister call, it passes it through a filter and then routes it to a replica node on the correct subnet in the IC.

Filtering within the boundary node consists only of rate-limiting. The rate-limits are in place to protect the IC from being overwhelmed with external accesses.

After an API canister call passed the filtering stage, the boundary node infers the destination canister ID and uses the routing table to look up the subnet in which this canister is hosted. It then randomly chooses a replica within that subnet to which it forwards the API call. The random selection of the target replica ensures that an API call eventually reaches an honest node when the client keeps retrying.

Finally, the boundary node forwards the API canister call to the selected replica node in the core of the IC.

Since the API Node is simply passing the API canister call on to the IC, no trust is required.

HTTP Gateway

The HTTP endpoint is served through two main domains: ic0.app and icp0.io. In the following, we use for simplicity only ic0.app, even though both domains could be used equally.

Unfortunately, browsers don't natively support API canister calls and therefore cannot directly talk to the canisters hosted on the IC. The HTTP gateway protocol bridges that gap by providing a mechanism to translate HTTP requests into API canister calls allowing a client to interact with canisters. A gateway can be implemented in various forms (e.g., as a stand-alone proxy, as a browser plugin, or as a service worker).

The boundary nodes provide with icx-proxy one implementation of the HTTP gateway protocol, which runs directly on the boundary node and operates in two different modes:

Enforcing response verification under <canister_id>.ic0.app;

Permissive response verification under <canister_id>.raw.ic0.app.

However, before serving any HTTP request, the HTTP Gateway first passes the incoming request through a filter, which can be used to implement content filtering allowing operators to comply with local legal frameworks (e.g., blocking gambling services in a particular geography). To learn more about content filtering see Content Filtering via The Boundary Nodes.

Then, the requests are passed on to icx-proxy, which translates the HTTP requests into API canister calls. These API canister calls are passed onto the API endpoint of the boundary node, which forwards it to a replica in the IC.

Upon receiving the response, icx-proxy checks certificate of the response and constructs an HTTP response back to the client. In enforcing mode, icx-proxy only sends the response to the client if it is correctly certified and an error otherwise. In permissive mode, icx-proxy only checks the certificate if there is one. The permissive mode is mainly required for legacy canisters that do not implement response verification or for dynamic responses that cannot easily be certified.

Additional Features of the Boundary Nodes

Globally-Distributed

The boundary nodes serving ic0.app are globally distributed and organized in regional pools. All requests are directed to the geographically closest pool and load balanced over the instances within that pool. The health of the boundary nodes is constantly monitored and in case of failure, boundary nodes will be removed from the pools.

SEO

The HTTP gateway on the boundary nodes allows the dapps running on the Internet Computer to seamlessly integrate into the Web 2.0 world. These dapps can be indexed by search engines and their metadata can be read in order to generate previews and cards on social platforms.

Caching

To improve the user-perceived performance of the dapps hosted on the IC, the boundary nodes currently provide response for HTTP assets. Responses to requests are cached for 10s.

Future Boundary Node Developments

To follow future boundary node developments check out the public roadmap, the IC developer forum and the thread on the future boundary node architecture.

@@ Line 1: / Line 1: @@
-The boundary nodes are the gateway to the Internet Computer (IC), which allow users to seamlessly access the canister smart contracts running on it. The following figure shows how the boundary nodes form the edge of the IC and all accesses to the IC have to go through one of the boundary nodes.
+The boundary nodes are the gateway to the Internet Computer (IC), and allow users to seamlessly access the canister smart contracts running on it. The following figure shows how the boundary nodes form the edge of the IC and all accesses to the IC have to go through one of the boundary nodes.
 [[File:High-Level Overview.png|600px|center]]
@@ Line 6: / Line 6: @@
 At a closer look, boundary nodes consist of two parts: the API node, which provides an endpoint for [https://internetcomputer.org/docs/current/references/ic-interface-spec/#http-interface API canister calls], and the HTTP gateway, which provides an HTTP endpoint for users to access the canisters hosted on the IC with their stock browser.
+[[File:Boundary Node Diagrams - BN Internals.png|alt=|center|800x800px]]
-[[File:Boundary Node Overview.png|800px|center]]
 === API Node ===
-The API endpoint resides at <code>ic0.app/api/v2</code> and is specified in the [https://internetcomputer.org/docs/current/references/ic-interface-spec/#http-interface IC’s Interface Specification].
+The API endpoint resides at <code>icp-api.io/api/v2</code> and is specified in the [https://internetcomputer.org/docs/current/references/ic-interface-spec/#http-interface IC’s Interface Specification].
-Whenever a boundary node receives an API canister call, it passes it through a filter and then routes it to the right replica node in the IC.
+Whenever a boundary node receives an API canister call, it passes it through a filter and then routes it to a replica node on the correct subnet in the IC.
-Filtering within the boundary node consists of rate-limiting and an operator-maintained denylist. The rate-limits are in place to protect the IC from being overwhelmed with external accesses. The denylist allows a boundary node operator to comply with local legal frameworks (e.g., blocking gambling services in a particular geography).
+Filtering within the boundary node consists only of rate-limiting. The rate-limits are in place to protect the IC from being overwhelmed with external accesses.
-After an API canister call passed the filtering stage, the boundary node extracts infers the destination canister ID and uses the routing table to look up the subnet in which this canister is hosted. It then randomly chooses a replica within that subnet to which it forwards the API call. The random selection of the target replica ensures that an API call eventually reaches an honest node when the client keeps retrying.
+After an API canister call passed the filtering stage, the boundary node infers the destination canister ID and uses the routing table to look up the subnet in which this canister is hosted. It then randomly chooses a replica within that subnet to which it forwards the API call. The random selection of the target replica ensures that an API call eventually reaches an honest node when the client keeps retrying.
 Finally, the boundary node forwards the API canister call to the selected replica node in the core of the IC.
@@ Line 25: / Line 24: @@
 === HTTP Gateway ===
-Unfortunately, not all applications natively support API canister calls and therefore cannot directly talk to the canisters hosted on the IC. The [https://internetcomputer.org/docs/current/references/ic-interface-spec/#http-gateway HTTP gateway protocol] bridges that gap by enabling canisters to handle conventional HTTP requests allowing, for example, browsers to interact with canisters. A gateway implementing this protocol translates between HTTP requests and API canister calls and can be implemented in various forms (e.g., as a stand-alone proxy, as a browser plugin, or as a [https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API service worker]).
+The HTTP endpoint is served through two main domains: <code>ic0.app</code> and <code>icp0.io</code>. In the following, we use for simplicity only <code>ic0.app</code>, even though both domains could be used equally.
-The boundary nodes provide two different implementations of the HTTP gateway protocol:
-* Service worker: under <code><canister_id>.ic0.app</code>, the boundary nodes serve a [https://www.npmjs.com/package/@dfinity/service-worker service worker], which is installed in the browser and acts as an HTTP gateway directly in the user’s browser;
+Unfortunately, browsers don't natively support API canister calls and therefore cannot directly talk to the canisters hosted on the IC. The [https://internetcomputer.org/docs/current/references/ic-interface-spec/#http-gateway HTTP gateway protocol] bridges that gap by providing a mechanism to translate HTTP requests into API canister calls allowing a client to interact with canisters. A gateway can be implemented in various forms (e.g., as a stand-alone proxy, as a browser plugin, or as a [https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API service worker]).
-* <code>icx-proxy</code>: under <code><canister_id>.raw.ic0.app</code>, the boundary node runs [https://github.com/dfinity/icx-proxy <code>icx-proxy</code>], an HTTP gateway implementation suitable for all clients that do not support a service worker.
+The boundary nodes provide with <code>icx-proxy</code> one implementation of the HTTP gateway protocol, which runs directly on the boundary node and  operates in two different modes:
-==== Service Worker ====
+* Enforcing response verification under <code><canister_id>.ic0.app</code>;
-[[File:Service Worker Flow.png|900px|center]]
+* Permissive response verification under <code><canister_id>.raw.ic0.app</code>.
-When accessing <code><canister_id>.ic0.app</code>, the boundary node returns a service worker implementing the HTTP gateway protocol, which is installed directly in the user’s browser (step 1 and 2). From then on, the service worker will intercept all HTTP requests and translate them to API canister calls (step 3). These API canister calls will then go through the API endpoint of the boundary node to the IC (step 4). The replica sends the response back through the boundary node to the service worker (step 5 and 6). For all responses, the service worker verifies the correctness of the response and only translates it into a proper HTTP response for the browser if it passes all the checks (step 7).
+However, before serving any HTTP request, the HTTP Gateway first passes the incoming request through a filter, which can be used to implement content filtering allowing operators to comply with local legal frameworks (e.g., blocking gambling services in a particular geography). To learn more about content filtering see [[Content_Filtering_via_Boundary_Nodes|Content Filtering via The Boundary Nodes]].
-==== <code>icx-proxy</code> ====
+Then, the requests are passed on to <code>icx-proxy</code>, which translates the HTTP requests into API canister calls. These API canister calls are passed onto the API endpoint of the boundary node, which forwards it to a replica in the IC.
-The HTTP Gateway endpoint implements the HTTP gateway protocol, which translates between HTTP requests and API canister calls. This endpoint resides at <code><canister_id>.raw.ic0.app</code>. Whenever a boundary node receives such a request, it forwards it to <code>icx-proxy</code>, a service running directly on the boundary node that implements the HTTP gateway protocol. <code>icx-proxy</code> translates the HTTP requests into API canister calls and forwards them to the API endpoint of the boundary node. It verifies the certificates of the responses and constructs an HTTP response to send back to the client. Here, the user needs to trust the boundary node as the boundary node is constructing the API calls and verifying the correctness of the IC’s response.
+Upon receiving the response, <code>icx-proxy</code> checks certificate of the response and constructs an HTTP response back to the client. In ''enforcing mode'', <code>icx-proxy</code> only sends the response to the client if it is correctly certified and an error otherwise. In ''permissive mode'', icx-proxy only checks the certificate if there is one. The permissive mode is mainly required for legacy canisters that do not implement response verification or for dynamic responses that cannot easily be certified.
 == Additional Features of the Boundary Nodes ==
@@ Line 51: / Line 48: @@
 === SEO ===
-Bots and crawlers, such as the ones used by search engines, unfortunately do not support service workers and are therefore not able to index content hosted under <code>ic0.app</code> out-of-the-box. However, they are able to access all the content under <code>raw.ic0.app</code> as the translation from HTTP requests to API calls happens within the boundary node. Therefore, boundary nodes detect all accesses of crawlers and bots to <code>ic0.app</code> and internally redirect them to <code>icx-proxy</code>. This allows the dapps running on the Internet Computer to seamlessly integrate into the Web 2.0 world. These dapps can be indexed by search engines and their metadata can be read in order to generate previews and cards on social platforms.
+The HTTP gateway on the boundary nodes allows the dapps running on the Internet Computer to seamlessly integrate into the Web 2.0 world. These dapps can be indexed by search engines and their metadata can be read in order to generate previews and cards on social platforms.
 === Caching ===
-To improve the user-perceived performance of the dapps hosted on the IC, the boundary nodes currently provide response caching. Responses to requests are cached for 1s.
+To improve the user-perceived performance of the dapps hosted on the IC, the boundary nodes currently provide response for HTTP assets. Responses to requests are cached for 10s.
 == Future Boundary Node Developments ==
@@ Line 63: / Line 60: @@
 ==See Also==
 * '''The Internet Computer project website (hosted on the IC): [https://internetcomputer.org/ internetcomputer.org]'''
+* [[Content Filtering via Boundary Nodes]]