Serve several buckets from one address, step by step

One address of your own, such as cdn.example.com, can serve files from several buckets and one video library, each under its own folder. You keep the addresses your pages and apps already use, and plycdn decides which bucket answers each one. This page takes you from the list of routes to a check that every folder is served. The reference is in API; adding the address itself is in Your own domain.

You need: a custom domain that is active and whose own bucket is private; the buckets (and, if you want one, the video library) to serve; an admin key to save a table; and one of plycdn's server packages (ASP.NET Core, Node.js or Python) or the API with your key. Routes can point at the buckets and video libraries of your organization and of its sub-organizations.

1When to use it

  • Your old setup served several folders from one address. For example cdn.example.com/org-content/videos/… came from one place, cdn.example.com/org-content/documents/… from another and cdn.example.com/assets/… from a third. Give each folder its own bucket here and nothing that links to those addresses has to change.
  • You want one address for several customers or products, each in its own bucket, without a different hostname for each.
  • You are moving from another cloud and your pages still use one gateway address: Moving from another cloud.

2How a route table works

A table is a list of routes. Each route says "paths that start with this folder go to this bucket".

  • Prefix. Whole folders ending in /, such as org-content/videos/. When more than one route matches, the longest prefix wins, so org-content/videos/live/ can go to a different bucket from org-content/videos/.
  • Remove the prefix (stripPrefix). Off: the bucket sees the whole path, so /org-content/videos/intro.mp4 is the file org-content/videos/intro.mp4. On: it sees what follows the prefix, so the same address is the file intro.mp4. Turn it on when the bucket holds the files without the folder name.
  • The video library. One route can point at a video library. It has no prefix: it serves your players' addresses (/v/… and /_s/…) on this address. At most one per address.
  • The default route. The domain's own bucket answers every address no route matches. Turn it off to answer those addresses with a plain "not found" page instead.
  • Up to 50 routes per address. Saving takes effect within about a minute, with no DNS or certificate change, and works on a domain that already serves traffic.

For the example above, the table is:

Prefix Bucket Remove the prefix
org-content/videos/ acme-videos no (files are stored under that folder)
org-content/documents/ acme-documents yes (files are stored without it)
assets/ acme-assets no
(none) acme-library (a video library) not used

and acme-main, the domain's own bucket, answers every other path.

3Set it up in the dashboard

  1. Domains & routing → Routing lists every address you serve, its rules and its targets. Open the address, then its Rules tab. (The Map tab shows where each request goes, in the order the rules are checked. The same rules are on the domain's Routes tab under Custom domains.)
  2. Choose Add rule, then Send to buckets (the rules above) or Redirect (see Redirect a path). For a bucket, type the prefix, choose the bucket (or the video library) in Target, and tick Remove the prefix if the bucket stores the files without the folder name. A video library needs no prefix.
  3. Leave Serve the domain's own bucket for every other path on, or turn it off to answer other paths with "not found".
  4. Choose Save routes. It is live within about a minute. Check it on the Map tab.

A route whose bucket was deleted shows Broken: its prefix falls back to the default route until you change it. Each save is kept as a version in Earlier versions, with Restore beside it.

4Set it up from your code

Reading a domain's routes works with any key. Saving and restoring need an admin key.

GET  /api/content/v1/domains/{domainId}/routes
PUT  /api/content/v1/domains/{domainId}/routes
POST /api/content/v1/domains/{domainId}/routes/restore      {"version": 2}

PUT replaces the whole table. Send the version you last read in If-Match so that two people saving at once cannot overwrite each other: the second is refused with version_conflict.

ASP.NET Core

var table = await storage.GetDomainRoutesAsync(organizationId, domainId);

var saved = await storage.SetDomainRoutesAsync(organizationId, domainId, new DomainRoutesBody
{
    DefaultRoute = true,
    Routes = new[]
    {
        new DomainRoute("org-content/videos/", videosBucketId),
        new DomainRoute("org-content/documents/", documentsBucketId, StripPrefix: true),
        new DomainRoute("assets/", assetsBucketId),
        new DomainRoute(null, libraryId),                 // the video library
    },
}, ifMatch: table.Version);

// Go back to an earlier table:
await storage.RestoreDomainRoutesAsync(organizationId, domainId, version: 2);

Node.js

const table = await storage.getDomainRoutes(organizationId, domainId);

const saved = await storage.setDomainRoutes(organizationId, domainId, {
  defaultRoute: true,
  routes: [
    { pathPrefix: 'org-content/videos/', bucketId: videosBucketId },
    { pathPrefix: 'org-content/documents/', bucketId: documentsBucketId, stripPrefix: true },
    { pathPrefix: 'assets/', bucketId: assetsBucketId },
    { pathPrefix: null, bucketId: libraryId },            // the video library
  ],
}, { ifMatch: table.version });

// Go back to an earlier table:
await storage.restoreDomainRoutes(organizationId, domainId, 2);

Python

table = storage.get_domain_routes(organization_id, domain_id)

saved = storage.set_domain_routes(organization_id, domain_id, {
    "defaultRoute": True,
    "routes": [
        {"pathPrefix": "org-content/videos/", "bucketId": videos_bucket_id},
        {"pathPrefix": "org-content/documents/", "bucketId": documents_bucket_id, "stripPrefix": True},
        {"pathPrefix": "assets/", "bucketId": assets_bucket_id},
        {"pathPrefix": None, "bucketId": library_id},      # the video library
    ],
}, if_match=table["version"])

# Go back to an earlier table:
storage.restore_domain_routes(organization_id, domain_id, 2)

Every answer is the saved table: defaultRoute, routes (each with a status of ok or broken), version, updatedAt and the last 20 versions. A domain that never had a table answers version 0 with the default route on.

5Sign links on the shared address

A link to a private bucket's file on a shared address is signed over the full path the viewer sees, prefix included. That keeps a link made for one folder from working under another. Links to a public bucket's route need no signature: use the plain address.

Sign on the shared address's hostname. plycdn accepts it for every bucket and video library a route of that address points at: their signing profile lists the address under routes (one entry per route, with its pathPrefix and stripPrefix), and the server packages read it from there. What else to give depends on the route:

  • The route removes the prefix (the bucket holds intro.pdf, viewers open /org-content/documents/intro.pdf): give the address's hostname, the route's prefix, and the file's key as stored.
  • The route keeps the prefix (the bucket holds org-content/videos/intro.mp4 and viewers open the same path): give the hostname and the key as stored, which already starts with the prefix. Do not give the prefix: it would be added twice.
  • The video library route: sign videos as you do today, with the hostname set to the shared address. The player's addresses (/v/…, /_s/…) never carry a prefix.

ASP.NET Core

var link = await signer.SignAsync(organizationId, documentsBucketId, "intro.pdf",
    new PlycdnSignOptions { Hostname = "cdn.example.com", PathPrefix = "org-content/documents/", Ttl = TimeSpan.FromMinutes(5) });
// https://cdn.example.com/org-content/documents/intro.pdf?token=…

var kept = await signer.SignAsync(organizationId, videosBucketId, "org-content/videos/intro.mp4",
    new PlycdnSignOptions { Hostname = "cdn.example.com" });

Node.js

const link = await signer.sign(organizationId, documentsBucketId, 'intro.pdf',
  { hostname: 'cdn.example.com', pathPrefix: 'org-content/documents/', ttlSeconds: 300 });
// https://cdn.example.com/org-content/documents/intro.pdf?token=…

const kept = await signer.sign(organizationId, videosBucketId, 'org-content/videos/intro.mp4', { hostname: 'cdn.example.com' });

Python

link = signer.sign(organization_id, documents_bucket_id, "intro.pdf",
                   hostname="cdn.example.com", path_prefix="org-content/documents/", ttl_seconds=300)
# https://cdn.example.com/org-content/documents/intro.pdf?token=…

kept = signer.sign(organization_id, videos_bucket_id, "org-content/videos/intro.mp4", hostname="cdn.example.com")

The API. POST /api/content/v1/sign with {"bucketId": "…", "key": "intro.pdf", "hostname": "cdn.example.com", "pathPrefix": "org-content/documents/"}; leave out pathPrefix for a route that keeps its prefix.

When you save or restore a table, plycdn sends signing_profile.changed (reason domains_changed) for every bucket and library the change adds or removes, so the server packages pick up the new routes at once. Without the webhook they notice within the hour, or on the first link for an address they do not know yet.

The browser packages only show addresses they are given, so they need no change: have your server sign the link and pass it to the page.

6Redirect a path

A redirect rule sends viewers who ask for a folder, or for the whole address, to another address. Use it when a folder moved, when an old address should lead to the new one, or to send everything on old.example.com to your new site.

  • Prefix. A folder ending in /, such as old-docs/, or an empty prefix for the whole address.
  • Where to (location). A full address starting with https:// or http://, at most 2,048 characters, with no user name, password or # part.
  • Permanent redirect (permanent). On sends 301, which browsers and search engines remember; off sends 302, for a move that may change. For requests other than GET and HEAD (an upload, say) viewers get 308 or 307, which keep the method.
  • Keep the rest of the path (keepPath). On adds what follows the prefix to the end of location: with prefix old-docs/ and location https://www.example.com/docs/, /old-docs/setup/intro goes to https://www.example.com/docs/setup/intro.
  • Keep the query (keepQuery). On keeps the viewer's ?a=1&b=2 on the new address.

Redirects are checked before the rules that send to buckets, and the longest matching prefix wins. A redirect on the whole address (empty prefix) also redirects the video player's addresses (/v/…) and share addresses (/_s/…), so players and share links on that address stop working: use a folder prefix unless you mean to move everything. A browser's OPTIONS check before a cross-site request to a redirected path gets the redirect too, not a permission answer.

In the dashboard: Domains & routing → Routing → the address → Rules → Add rule → Redirect. Type the prefix and the address to send viewers to, and turn on Permanent redirect, Keep the rest of the path or Keep the query as you need. Choose Save routes.

ASP.NET Core

var saved = await storage.SetDomainRoutesAsync(organizationId, domainId, new DomainRoutesBody
{
    DefaultRoute = true,
    Routes = new[]
    {
        DomainRoute.Redirect("old-docs/", "https://www.example.com/docs/", permanent: true, keepPath: true, keepQuery: true),
        new DomainRoute("assets/", assetsBucketId),
    },
}, ifMatch: table.Version);

Node.js

await storage.setDomainRoutes(organizationId, domainId, {
  defaultRoute: true,
  routes: [
    { kind: 'redirect', pathPrefix: 'old-docs/', location: 'https://www.example.com/docs/',
      permanent: true, keepPath: true, keepQuery: true },
    { pathPrefix: 'assets/', bucketId: assetsBucketId },
  ],
}, { ifMatch: table.version });

Python

storage.set_domain_routes(organization_id, domain_id, {
    "defaultRoute": True,
    "routes": [
        {"kind": "redirect", "pathPrefix": "old-docs/", "location": "https://www.example.com/docs/",
         "permanent": True, "keepPath": True, "keepQuery": True},
        {"pathPrefix": "assets/", "bucketId": assets_bucket_id},
    ],
}, if_match=table["version"])

The API body for a redirect is {"kind": "redirect", "pathPrefix": "old-docs/", "location": "https://www.example.com/docs/", "permanent": true, "keepPath": true, "keepQuery": true}.

7Share traffic between buckets, with backups

A rule can name 1 to 5 buckets instead of one. Each gets a share of the viewers, a whole number from 1 to 100. Shares are relative: 70 and 30 send 70% and 30% of viewers, and so do 7 and 3. Use it to spread delivery between two storage locations, to move a folder gradually from one bucket to another, or to keep a backup bucket that takes over when the first cannot answer.

  • Viewers stay put. A viewer is sent to the same bucket for every file under the rule (every segment of a video, every page of a course), so a page never mixes two buckets. Changing the shares moves only the viewers who must move.
  • Backups. When the bucket chosen for a viewer cannot answer, plycdn tries the next one, for GET and HEAD requests and only before any of the file has been sent: at most 3 tries, about 8 seconds each and 25 seconds in all. The file the viewer gets is the same; nothing in the address changes.
  • A bucket that cannot serve is skipped. A bucket that is paused or taken down shows Paused and is left out until it can serve again. A rule with every bucket down answers viewers with plycdn's "temporarily unavailable" page (503, with Retry-After: 30), never an empty page.
  • Same visibility. All the buckets of one rule must be public, or all private (route_targets_invalid). A video library rule has one library only.
  • Signing. Links to a private rule with several buckets are checked with the first bucket's key and access settings (allowed sites, countries, rate limit, address binding). In the dashboard the first bucket is marked Signs with. The server packages do this for you: sign with any of the rule's buckets and the package uses the first one's key, from the signing profile. With the API, POST /sign for any bucket of the rule signs with the first one when the buckets are in the same organization; otherwise sign through the first bucket's organization. A link you sign yourself with another bucket's key is refused with 403. If the first bucket is paused, its links still work while the others serve.

In the dashboard: Domains & routing → Routing → the address → Rules → Add rule → Send to buckets. Type the prefix, Add each bucket and give it a Share, with the first bucket the one that signs. Choose Save routes.

ASP.NET Core

await storage.SetDomainRoutesAsync(organizationId, domainId, new DomainRoutesBody
{
    DefaultRoute = true,
    Routes = new[]
    {
        DomainRoute.Forward("videos/", new[]
        {
            new DomainRouteTarget(mumbaiBucketId, 70),
            new DomainRouteTarget(backupBucketId, 30),
        }),
    },
}, ifMatch: table.Version);

Node.js

await storage.setDomainRoutes(organizationId, domainId, {
  defaultRoute: true,
  routes: [
    { pathPrefix: 'videos/', targets: [
      { bucketId: mumbaiBucketId, share: 70 },
      { bucketId: backupBucketId, share: 30 },
    ] },
  ],
}, { ifMatch: table.version });

Python

storage.set_domain_routes(organization_id, domain_id, {
    "defaultRoute": True,
    "routes": [
        {"pathPrefix": "videos/", "targets": [
            {"bucketId": mumbai_bucket_id, "share": 70},
            {"bucketId": backup_bucket_id, "share": 30},
        ]},
    ],
}, if_match=table["version"])

Give a rule bucketId or targets, never both (route_bucket_and_targets). The answer lists each rule with its kind, and each bucket with its share and a status of ok, paused or broken. A rule you saved with one bucketId is shown as one bucket with a share of 100 and keeps working as before.

Sign as you do today, with any bucket of the rule:

var link = await signer.SignAsync(organizationId, backupBucketId, "intro.mp4",
    new PlycdnSignOptions { Hostname = "cdn.example.com", PathPrefix = "videos/" });   // signed with the first bucket's key
const link = await signer.sign(organizationId, backupBucketId, 'intro.mp4', { hostname: 'cdn.example.com', pathPrefix: 'videos/' });
link = signer.sign(organization_id, backup_bucket_id, "intro.mp4", hostname="cdn.example.com", path_prefix="videos/")

8Check that it works

  1. Read the table again (GET /domains/{domainId}/routes, or open the domain's page): every route says ok, and version is the one you saved.

  2. Wait about a minute, then open one address under each prefix. For a private bucket use a freshly signed link:

    curl -I "https://cdn.example.com/org-content/documents/intro.pdf?token=…"
    

    200 means that route is serving. A plain 404 page means no route (and no default route) matched that path.

  3. Check that a link made for one folder does not open under another: change documents to videos in the signed address. It is refused, because the signature covers the whole path.

  4. Delivery → Delivery analytics counts each file against the bucket that served it, so each route's delivery shows on its own bucket.

  5. Account & security → Audit log shows every save as domain.routes_changed, with the table before and after.

  6. A redirect: curl -I "https://cdn.example.com/old-docs/setup/intro" answers 301 (or 302) with a location: line that is the address you set. The Map tab shows redirects first, in the order they are checked.

  7. Shared traffic: open several files under the rule from different browsers or curl --interface addresses and compare which bucket answers (the Map tab lists each bucket and its share). Pause one bucket to try a backup: viewers still get their files from the others. Delivery → Delivery analytics shows the traffic per bucket, and the "Shared addresses" dashboard in Logthread (see Logthread) shows redirects, backups used and rules with every bucket down.

  8. Before or after you save, try an address without sending any traffic: Domains & routing → Routing → the address → Rules (or Map) → Test an address. Type a path or a full address, a Sample viewer (a viewer's IP address) and the Request (GET, HEAD, POST or PUT). It shows which rule answers and its number in the order rules are checked. For a redirect it shows the address viewers are sent to and the status (301, 302, 307 or 308). For a rule with buckets it shows the bucket that viewer gets (Serving now), the backups in order, the bucket links are checked with (Signs with) and the path the bucket is asked for. When every bucket of the rule is paused, it shows the "temporarily unavailable" page. Otherwise it shows the domain's own bucket, or "not found". On the Rules tab the test includes changes you have not saved yet; on the Map it uses only the rules that are saved, which are what viewers get now.

9Errors and fixes

Code What it means What to do
route_prefix_invalid (422) A prefix is not whole folders ending in /, or a bucket route has none Use a prefix such as org-content/videos/: no . or .. folder, no //, \, %, ? or #
route_prefix_reserved (422) A bucket route's prefix starts with v/ or _s/, which belong to the video library route Choose another folder, such as videos/
route_prefix_duplicate (422) Two routes share a prefix Give each route its own prefix (one inside another is fine)
route_too_many (422) More than 50 routes Remove some, or put several folders in one bucket
route_video_twice (422) More than one video library route Keep one
route_target_not_found (404) A bucket or library does not exist, or is not yours Pick it from your buckets and libraries
route_target_scope (403) Your key may not reach that bucket or library Use a key that covers its organization
routes_need_private_address (409) The domain's own bucket is public, so its domain cannot carry routes Add the address to a private bucket, then add routes
route_redirect_invalid (422) A redirect has no usable location (not an https:// or http:// address, over 2,048 characters, or with a user name, password or # part), or a prefix that is not whole folders Give a full address such as https://www.example.com/docs/, and a prefix ending in / (or empty for the whole address)
route_redirect_loop (422) A redirect sends viewers back to the same address, to a folder that redirects again, or round a circle of redirects Send it to a different address, or to a folder no redirect matches
route_targets_invalid (422) A rule has no bucket or more than 5, the same bucket twice, a share outside 1 to 100, buckets that are not all public or all private, or a video library with other buckets Give 1 to 5 different buckets, whole shares from 1 to 100, buckets of one visibility, and one library on its own
route_bucket_and_targets (422) A rule has both bucketId and targets Keep one: bucketId for one bucket, targets for several
version_conflict (409) Someone saved a newer table Read the table again, apply your change, save again
route_version_not_found (404) That version is not among the last 20 Read versions and restore one of them
domain_not_active (409) when signing No route of that address points at this bucket (or the address is not active yet) Check the route's bucket, wait a minute after saving, or sign on the bucket's own address
validation_error (422), field pathPrefix, when signing The route removes its prefix and none was given, or it keeps its prefix and one was given Give the route's prefix for a route that removes it; give only the stored key for one that keeps it
admin_key_required (403) Saving and restoring need an admin key Use an admin key from Developers → API keys
domain_not_found (404) No such domain here Check the domain ID and the organization

10Where to go next