WebAssembly build#

The in-browser WebAssembly build of git2cpp is intended to behave as similar as possible to other builds but there are some differences when remotely accessing remote servers, in particular with blocking requests and the requirement for a CORS proxy server.

Blocking requests#

Remote git2cpp requests in non-WebAssembly builds are progressive and feedback is provided as the data is streamed back from the remote. But in WebAssembly builds such remote requests are blocking and no feedback can be provided until the entire response is received back from the remote. This can be a long time to wait without feedback, and if there is an error such that a response is not received it could block forever, leaving the in-browser terminal unusable.

Hence the WebAssembly build limits http(s) requests with a timeout that defaults to 10 seconds. This timeout can be increased using the GIT_HTTP_TIMEOUT environment variable.

In addition, when a git2cpp response is received that is larger than 10 MB, a prompt is presented to the user to confirm whether to proceed to unpack the response or not. Note that the size of the response may be smaller or larger than the size of the directory structure it unpacks to.

CORS proxy server#

The fetching of resources in a browser from one domain to another is often limited by a browser security feature called Cross-Origin Resource Sharing (CORS). For this to be allowed the target domain must indicate it is happy to accept cross-origin requests by adding certain headers to https responses. Most git servers such as github.com do not add these headers, so a git2cpp clone from github.com will fail with a CORS error if run from within a browser whereas there is no such limitation if run from a terminal of a real computer.

The solution to this problem is to use a separate CORS proxy server. The git2cpp remote request is sent to this intermediate server which send the request to the target server and as this request is coming from outside a browser it is not subject to CORS restrictions. The proxy receives the response from the target server and adds the required CORS headers before returning it to git2cpp.

Various public CORS proxy servers are available for use or you serve your own. It can be useful to serve your own on localhost when experimenting to confirm that everything works as expected before moving on to a more complex solution. Be aware that the CORS proxy server is able to read the content of your request so be careful if you are using authentication tokens.

The GIT_CORS_PROXY environment variable is used to specify how the target URL is encoded in the CORS proxy URL.

Example running a local CORS proxy server#

If you are running a local cockle or JupyterLite terminal deployment you can also run a local CORS proxy such as CORS Anywhere to test it out. In a separate terminal on your host machine on which you have nodejs available, cd to a new clean directory, and download and run the CORS proxy server using:

npm install cors-anywhere
HOST=localhost PORT=8881 node node_modules/cors-anywhere/server.js

This will start the CORS proxy server listening on http://localhost:8881/. To use this in your local cockle or JupyterLite terminal deployment in your browser set the CORS_PROXY_URL to be

export GIT_CORS_PROXY=http://localhost:8881/

and then try a git2cpp clone using something like:

git2cpp clone https://github.com/some-organisation/some-repository

Example using a public CORS proxy server#

There is a public instance of CORS Anywhere available at https://cors-anywhere.herokuapp.com/. This can be used for demonstration purposes but it requires an explicit opt-in and your access will be time-limited. To request temporary access go to https://cors-anywhere.herokuapp.com/ and follow the instructions there.

Once you have access, you can try this out in one of the public deployments such as those at https://jupyterlite.github.io/cockle or https://jupyterlite.github.io/terminal.

Set the CORS_PROXY_URL to be

export GIT_CORS_PROXY=https://cors-anywhere.herokuapp.com/