Skip to main content

Media Proxy Integration

In priint:cloud rendering service the responsibility of retrieving images via HTTP is delegated to a special service: the media proxy. If comet_pdf tries to fetch an image using GET https://some/url it will not connect to the internet directly but instead call the media proxy service to do the actual HTTP call.

This allows us to configure more complex rules for authentication (e.g. OAuth2), for custom HTTP headers, or caching, than comet allows. Different rules can be configured for different base URIs. An example follows below.

To use media proxy all image placeholders must use comet scripting code as given in the snippets below. This relies on an environment variable GRID_PROXY_URL that is automatically provided by the container environment. Alternatively, in CScript a global variable gMediaProxy exists with similar content. GRID_PROXY_URL contains the base address of the proxy service within the cloud environment.

Use in Comet Scripting​

Python​

import comet
import os

def toProxyUrl(originalUrl):
    return os.getenv("GRID_PROXY_URL") + '?' + originalUrl

originalUrl = "https://foo/bar/img.png"
proxyUrl = toProxyUrl(originalUrl)
comet.wlog("Image URL: %s", proxyUrl)
comet.frame.image(gFrame, proxyUrl, 5, 100.0)

CScript​

void toProxyUrl(String remote_url, String proxy_url) {
  if (strlen(gMediaProxy) > 0) {
    string::append(proxy_url, gMediaProxy);
  }
  string::append(proxy_url, remote_url);
}    

void main() {
  String remote_url = string::alloc();
  String proxy_url = string::alloc();
  string::set(remote_url, "https://foo/bar/img.png");
  toProxyUrl(remote_url, proxy_url);
  wlog("", "Image URL: %s", proxy_url);
  frame::image(gFrame, proxy_url, 5, 100.0);
  string::release(proxy_url);
  string::release(remote_url);
}

Note that gMediaProxy already ends on the suffix "?".

Configuration of the MediaProxy​

The configuration of the media proxy depends on the tenant/project. The config file is in the “ion” format, stored on the priint:cloud in the tenants/{tenant}/projects/{project}/config.ion file.

Usually a priint:cloud administrator will configure this file for the tenant/project you are working on. This will be done once at the start of the project but can be modified if necessary.

The file is read on-demand, i.e., when the first request concerning a specific project is encountered. The file is cached within the application until the message broker signals a change. This file contains settings for known outgoing connections. The file may be used by several grid applications and workers, not only media proxy.

tip

Media proxy is a part of priint:cloud core. Further details of the configuration is given in:

An Example​

{
  "connections": [
    {
      "url": "http://some.host.com",
      "authentication": {
        "type": "Basic",
        "username": "suedoe",
        "password": "******"
      },
      "follow-redirects": true
    },
    {
      "url": "https://another.host.com",
      "cache": {
        "max-duration": 3600,     /* one hour */
        "revalidate-after": 600   /* 10 minutes */
      },
      "headers": {
        "My.Special.Name": "hurz"
      },
      "authentication": {
        "type": "OAuth2",
        "grantType": "Password",
        "accessTokenUrl": "http://my.server.com/api/oauth/v1/token",
        "clientAuthentication": "Basic",
        "username": "hannib**",
        "password": "lect**"
      },
      "allow-insecure" : false
    }
  ]
}

The Connection Element​

  • url (required)
  • cache
    • max-duration (in sec)
      • max age of an entry in the cache even if the Cache-Control headers of the response would allow for more. The max age of an entry might additionally be restricted by settings of the cache implementation.
    • max-object-size (in bytes)
      • objects exceeding this threshold will never be cached
    • heuristic (default true)
      • Allow HttpClient to cache values without Cache-Control headers. Use rules given in RFC-2616.
    • revalidate-after (currently not supported)
    • ignoreCacheControl (default false)
      • If true this flag deactivates the RFC-2616 standards compliant mode. Data will be cached regardless of the caching headers send by the client only on the base of max-duration setting.
  • connect-timeout (in sec)
  • request-timeout (in sec)
  • headers
    • add any custom header with name and value
  • authentication (see example)
  • follow-redirects (default is false)

Caching​

Media proxy allows caching of resources (either RFC-2616 compliant or custom).

The cache is a shared resource between all comet_pdf processes running in parallel.

Caching will help if the image resources are used in many PDFs that are rendered around the same time. The cache will better help on smaller (< 200 KB) than on larger files (> 1 MB). You can configure the max-duration in the cache. But you should not expect that your files will grow so old. The memory space for caching is shared between different projects - so new files from your own or from other projects may oust your entries.

As a recommendation:

  • use caching only if you use massive parallel rendering
  • set max-duration not longer than 5 min
  • set max-object-size to a small value, e.g. 524288 (i.e. 500 KB)