Network Manifesto #

In the Manifesto, which specifies resources necessary for the application, the "networks" field defines the connection destination used for communication. In particular, this specification is called the network manifesto.

How to specify connection destinations #

There are three ways of specifying connection destinations in the network manifesto; either by specifying a domain, the entire local network, or a multicast address. The first two methods serve a SOCKS proxy that allows connections to the specified addresses, and all communications happen through it. In the case of specifying the multicast address, regular communication is possible without an extra procedure.

How to specify domains #

A combination of domain, port and protocol can be specified.

Wildcard in the domain #

The domain you connect to can be partially matched by using wildcards(*).

Wildcards can be used in subdomain positions and will match any sequence of alphanumeric characters or hyphens.

Example: Amazon API Gateway

Using the following Amazon API Gateway REST API URL, if you want to match any restapi_id and region, specify it as *.execute-api.*.amazonaws.com.

https://{restapi_id}.execute-api.{region}.amazonaws.com

Wildcards must be specified in each label.

Example: The case of connecting {foo}.example.com and {bar}.{foo}.example.com

*.example.com and *.*.example.com should be specified.

Example: The case of connecting {foo}.example.com and example.com

*.example.com and example.com should be specified.

How to specify the entire local network #

A combination of local_addr, port, and protocol should be specified. This allows the Act to connect to the ranges of IPv4 private addresses (10/8, 172.16/12, 192.168/16) and IPv6 unique local addresses (FD00::/8).

For a detailed definition of the schema, see https://actcast.io/schema/v6/manifesto_schema.json.

Example: In the case of connecting to an HTTP server on the local network

If you want to access port 80 of a server located on the same local network as the device, set it as follows.

"networks": [
    { "local_addr": true, "port": 80, "protocol": "tcp" }
]

How to specify a multicast address #

Specify the multicast_addr, port, protocol, and direction. IP multicast communication is a one-way communication protocol with one-to-many communication. Therefore, direction specifies the direction of transmission and reception.

For a detailed definition of the schema, see https://actcast.io/schema/v6/manifesto_schema.json.

Example: In the case of receiving multimedia data from an RTP server

If you want to receive multicast data from an RTP server of 224.0.0.120, set it as follows.

"networks": [
    { "multicast_addr": "224.0.0.120", "port": 5001, "protocol": "udp", "direction": "recv" }
]

Connecting to the proxy #

ACTCAST_SOCKS_SERVER

The ACTCAST_SOCKS_SERVER is an environment variable that is set on starting the Actcast application container. This environment variable is set to the address and port number of the SOCKS proxy in the form <IP address>:<port number>.

Use the address contained in this environment variable to connect to the specified hosts when using either Specify domain name or Specify local network in the network manifesto.

Examples #

Here is an example of how to use the network manifesto.

Making an HTTP request to https://actcast.io in a Python app #

If you want to use the SOCKS proxy in your Python app, you can use the Requests and PySocks packages, for example.
To use them, add requests and pysocks to the pip list of the .actdk/dependencies.json, as follows:

{
  ...
  "pip": [
    ...
    "requests",
    "pysocks"
  ]
}

Then, specify the connections inside manifesto/*.json. This time, we want to access https://actcast.io, so we specify the following

{
  ...
  "networks": [
    {
      "domain": "actcast.io",
      "port": 443,
      "protocol": "tcp"
    }
  ]
}

Finally, call requests.get() with proxies. you need to specify socks5h as a URI Scheme and let the SOCKS proxy resolve the names.

import os
import requests

requests.get(
    'https://actcast.io',
    proxies={
        'https': f'socks5h://{os.environ["ACTCAST_SOCKS_SERVER"]}'
    }
)  # => <Response [200]>

Access another server on the local network with a Python app #

As in the Making an HTTP request to https://actcast.io in a Python app example, add requests and pysocks to the pip of the .actdk/dependencies.json

Then, on another machine on your local network, run $ python3 -m http.server 80 to start the server.

Next, specify "local_addr": true in the manifesto/*.json.

{
  ...
  "networks": [
    {
      "local_addr": true,
      "port": 80,
      "protocol": "tcp"
    }
  ]
}

Finally, call requests.get() with proxies. Unlike the Making an HTTP request to https://actcast.io in a Python app example, we don’t need to resolve the name, so we specify socks5 instead of socks5h.

import os
import requests
requests.get(
    'http://192.168.1.100',
    proxies={
        'http': f'socks5://{os.environ["ACTCAST_SOCKS_SERVER"]}'
    }
)  # => <Response [200]>