Get started

Network calls on the hosted phone

How the hosted phone sends your app's HTTP calls through a request proxy, the same on Android and iOS.

Edit on GitHub

The hosted phone sends an app's HTTP calls through a request proxy on the control plane, so the browser applies no CORS rules. It works the same on the Android and iOS skins.

Allowed hosts

The proxy only reaches the hosts on the app's allow-list. The owner stores the list with the set_network_allow command (owner sign-in only), for example:

json
["api.example.com", "*.cdn.example.com"]
  • A name matches that host only. *.example.com matches any subdomain, not example.com itself.
  • No scheme, port, path or IP address. A bad entry is refused with bad_param and nothing is stored.
  • @shipvo/schema exports the same validation (parseNetwork).

What the proxy checks

  • The caller has a signed-in session.
  • The host is on the app's list, on every redirect as well.
  • Every address the host resolves to is public. Private, loopback, link-local and cloud metadata addresses are refused, also when a redirect points there.
  • Ports 80 and 443 only, no credentials in the URL.
  • Request size, response size, time and request rate are limited per session. Usage quotas apply.
  • Hop-by-hop headers are removed. Shipvo session tokens and cookies are never forwarded. A site's Set-Cookie is not passed back.
  • An authorization header your app sends is forwarded to the declared host. It is dropped if a redirect leaves that host.

Every request from a signed-in session, allowed or refused, is recorded in device_log with the app, host, path (no query string), status and the reason for a refusal. A refused call answers with a JSON error and the x-shipvo-net-error header.

Network profiles

Run the same flow under different network conditions. A profile sets how long each fetch and XHR call waits and how often it fails. The numbers are simulation settings, not measurements of a real network.

ProfileLatency per requestDownload rateCalls that fail
online0 msunlimited0%
offline0 msnone100%
2g800 ms50 kbps2%
3g300 ms750 kbps1%
slow-4g150 ms1,600 kbps0%
spotty400 ms500 kbps30%
low-end-4g100 ms6,300 kbps0.5%

Works the same on the Android and iOS skins.

In a @shipvo/test test

ts
import { test, expect } from "@shipvo/test/vitest";

test("shows an error when offline", async ({ phone }) => {
  await phone.setNetwork("offline");
  await phone.tap("Load items");
  await phone.waitFor("Could not load items");
  expect(await phone.getNetwork()).toBe("offline");

  await phone.setNetwork("online");
  await phone.tap("Load items");
  await phone.waitFor("Items loaded");
});

setNetwork throws a PhoneError with code unknown_profile for a name that is not in the table. Mock rules from phone.mockNetwork still answer under any profile.

Over MCP

  • set_network_profile { session, profile } switches the profile. An unknown name fails with unknown_profile.
  • get_network_profile { session } returns the current name.

Each change is recorded in device_log as simulated.

In phone.json

json
{ "network": "slow-4g" }

The phone starts with that profile. An unknown name fails the session with bad_profile and says which names exist.

Troubleshooting

Every refused call answers with JSON { "error": "<code>" } and the same code in the x-shipvo-net-error header. Look the code up in device_log.

CodeStatusWhat it means and what to do
unauthorized401The session is not signed in. Sign in, then try again.
host_not_allowed403The host is not on the app's allow-list. Ask the owner to add it with set_network_allow. *.example.com does not match example.com itself, so list both.
blocked_address403The host is, or resolves to, a private, loopback, link-local or metadata address. Use a public host.
port_not_allowed403Only ports 80 and 443 are open. Drop the port from the URL.
credentials_in_url400Remove user:password@ from the URL and send an authorization header instead.
bad_scheme400Use an https: URL.
rate_limited429Too many requests from this session. Wait the retry-after seconds in the reply.
request_too_large, response_too_large413The body went over the size limit for a call. Send or fetch less per request.
too_many_redirects, bad_redirect502The server redirected too often, or to a URL that is not valid. Call the final URL.
dns_failed, upstream_failed502The host did not resolve or did not answer. Check the name, then retry.
timeout504The server took too long. Retry, or check that it answers.

If an authorization header goes missing after a redirect, the redirect left the declared host. Call the final host directly and list it.

Next steps

  • Device API: the same profiles from the device API.
  • Phone apps: data sources that call a host through this proxy.
  • Testing: write the offline and slow-network checks as typed tests.