Skip to content
P4 Software P4 Software / BarcoderX English

Add these docs to Claude

Ask Claude questions about these docs. Claude reads the published pages and links you back to them. Copy this address:

https://p4-software.opendocs.page/mcp

In claude.ai or Claude Desktop: open Settings, then Connectors, choose Add custom connector and paste the address.

In Claude Code, run:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

Deploying the label service

Deploying the label service

Applies to: BarcoderX Basic and Ultimate

Status: Built, not yet released. This page is for the person who puts the label service where other people can reach it. The service is a small program, described in The label service. It speaks plain http and it is meant to sit behind a web server that you run. The two configurations below are references, written from the documentation of nginx and Caddy, except the two lines that set X-Forwarded-Proto, which are written from general knowledge of those programs and were not checked in their documentation. They have not been run against a live service yet, so test them before you rely on them.

Why a web server in front

The service has limits of its own: the size of a template, the time of a request, the number of requests and connections of a caller, and the time it gives a caller to take an answer. They keep one caller from using the whole service. They are the last line, not the first. Put a web server in front of it, and let that server do four things:

  1. Handle https. The service speaks only http.
  2. Buffer the request and the answer. A caller that sends its template slowly, or reads its answer slowly, then spends the time of the web server and never reaches the service. The service gives a slow caller a few seconds and then drops it, and until then that caller holds only its own place and one connection, never a place for drawing. A buffering proxy takes even that away.
  3. Limit the connections for each address. The service limits the connections of a caller, but it cannot count the callers behind a proxy, so the proxy is the place to do it.
  4. Say who the caller is. The service limits the requests of each caller, and it must be told which caller sent a request that came through the proxy.

Required before a public launch. These four are required before you let anyone you do not know reach the service. Two more points do not depend on the web server: the pictures and the commands carry the evaluation mark until a license is registered, and the service is not for production use. Keep the .NET runtime that runs the service up to date.

The settings of the service behind a proxy

Edit settings.json next to the program:

{
  // Listen on this computer only. Only the proxy reaches the service.
  "listenAddress": "http://127.0.0.1:5187",

  // Believe the address that the proxy reports, from this proxy only.
  "network": {
    "trustForwardedHeaders": true,
    "trustedProxies": ["127.0.0.1"]
  }
}

With these settings:

  • The service listens only on this computer. Nobody reaches it except through the proxy.
  • Who the caller is. A connection from 127.0.0.1 is believed when it carries X-Forwarded-For, and the service takes the last address in that header, the one the proxy added itself (network.trustedProxyHops is 1 by default). The addresses to its left were sent by the caller and are ignored. A connection from any other address keeps its own address.
  • Connections from the proxy are not counted against limits.maxConnectionsPerClient, because all callers come through it. Limit them at the proxy, as below.
  • The proxy must add the address of the caller and must not pass the header on unchanged. The configurations below do that.
  • The proxy must also write X-Forwarded-Proto itself. The service sends Strict-Transport-Security only when the listed proxy says https (the entry at the right end of the header), so a proxy that passes the header of the caller on unchanged lets a caller on plain http make the service send it. The configurations below overwrite it. If your proxy serves plain http too, it must write http there. To send no such header at all, set network.sendStrictTransportSecurity to false.

If the proxy runs on another computer, list its address in network.trustedProxies and set listenAddress to an address of this computer that only the proxy can reach. An entry is a single address (10.0.0.5, 2001:db8::5) or a range (10.0.0.0/8), at most 32 entries. A range must be written exactly (10.0.0.1/8 is refused: its start is 10.0.0.0). "Any address" (0.0.0.0 or ::) and a range that covers every address or almost every address (0.0.0.0/0, ::/0, any range wider than /8 for IPv4 or /7 for IPv6, since two halves would cover everything too) are refused; such a range is allowed only if you also set network.acceptAnyProxyAddress to true, which you should not do, because then every caller is a trusted proxy and can choose its own address.

nginx

This is a complete server block with the settings that matter. The comments say what each part is for. The numbers are a first choice: the template limit of the service is 262,144 bytes by default, and the largest answers are 2,000,000 bytes (a picture) and 16,777,216 bytes (printer commands), so the buffers below hold the answers of a picture and spill the larger ones to a temporary file.

# Reference configuration for nginx in front of the BarcoderX label service.
# Change the name, the certificate paths and the numbers to fit your site.

# Count the connections and the requests of each client address.
# 10 MB of shared memory holds the state of many thousands of addresses.
limit_conn_zone $binary_remote_addr zone=bx_conn:10m;
limit_req_zone  $binary_remote_addr zone=bx_req:10m rate=30r/m;

upstream barcoderx_label_service {
    server 127.0.0.1:5187;
    keepalive 8;
}

server {
    listen 443 ssl;
    server_name labels.example.com;

    ssl_certificate     /etc/ssl/labels.example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/labels.example.com/privkey.pem;

    # A caller that sends its headers or its template slowly is dropped here,
    # and so is a caller that is slow to take the answer.
    client_header_timeout 10s;
    client_body_timeout   10s;
    send_timeout          15s;

    # The service refuses a template over 262144 bytes (its default). Refuse it here first.
    client_max_body_size 300k;

    # At most 20 connections and a steady 30 requests a minute for each address,
    # with a burst of 10. The service has its own, smaller limits behind this.
    limit_conn bx_conn 20;
    limit_req  zone=bx_req burst=10 nodelay;

    location / {
        proxy_pass         http://barcoderx_label_service;
        proxy_http_version 1.1;
        proxy_set_header   Connection "";
        proxy_set_header   Host $host;

        # Add the address of the caller to the header. $proxy_add_x_forwarded_for is
        # what the caller sent, with the address nginx saw appended at the end. The
        # service believes only that last address.
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;

        # Say which scheme the visitor used, replacing whatever the caller sent. The
        # service sends the Strict-Transport-Security header only when this says https.
        proxy_set_header   X-Forwarded-Proto $scheme;

        # Read the whole request here before the service sees it, and read the
        # whole answer from the service at once. A slow caller then spends nginx's
        # time, not a place of the service.
        proxy_request_buffering on;
        proxy_buffering         on;
        proxy_buffers           16 64k;
        proxy_busy_buffers_size 128k;
        proxy_max_temp_file_size 32m;

        proxy_connect_timeout 3s;
        proxy_send_timeout    15s;
        proxy_read_timeout    15s;
    }
}

Caddy

Caddy gets a certificate by itself for a real host name. This is a Caddyfile with the same intent. The comments say what each part is for.

# Reference configuration for Caddy in front of the BarcoderX label service.
# Change the host name and the numbers to fit your site.

{
    servers {
        timeouts {
            # A caller that sends its headers or its template slowly is dropped,
            # and so is a caller that is slow to take the answer.
            read_header 10s
            read_body   10s
            write       20s
            idle        30s
        }
        max_header_size 16KB
    }
}

labels.example.com {
    # The service refuses a template over 262144 bytes (its default). Refuse it here first.
    request_body {
        max_size 300KB
    }

    reverse_proxy 127.0.0.1:5187 {
        # Read the whole request here before the service sees it, and read the
        # whole answer from the service at once. Make the second number at least
        # as large as the largest answer you allow (limits.maxOutputBytes and
        # limits.maxCommandsBytes), or the answer is streamed and a slow caller
        # reaches the service.
        request_buffers  300KB
        response_buffers 20MB

        # Caddy sets X-Forwarded-For to the address it saw and, by default, ignores
        # the value that the caller sent. That is what the service needs.
        # Do not add trusted_proxies here unless another proxy is in front of Caddy.

        # Say which scheme the visitor used, replacing whatever the caller sent. The
        # service sends the Strict-Transport-Security header only when this says https.
        header_up X-Forwarded-Proto {http.request.scheme}
    }
}

Caddy does not limit the connections or the requests of one address by itself. Do it where your system allows: a firewall rule that counts the connections of each address, or a module for Caddy that limits requests. The service's own limits stay in force, but they are the last line only.

Azure App Service

App Service ends https at its network load balancers, and the app receives plain http. The load balancer is inside the private address ranges, and Microsoft's page for ASP.NET Core apps (configure-language-dotnetcore, the section "Detect HTTPS session") says to trust three private ranges and that they cannot be narrowed down further. List them in the settings:

"network": {
  "trustForwardedHeaders": true,
  "trustedProxies": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
}

The page writes the same ranges as ::ffff:10.0.0.0/104, ::ffff:172.16.0.0/108 and ::ffff:192.168.0.0/112; the service accepts that form too and treats it as the same. Without this, the service sees every visitor as the load balancer, so all visitors share one request at a time and one rate limit.

The same two settings make the service send the Strict-Transport-Security header: the load balancer tells the app that the visitor used https (X-Forwarded-Proto: https), and the service believes it only because the load balancer is listed. Nothing else is needed. To switch the header off, set network.sendStrictTransportSecurity to false (see Label service).

What to know about it:

  • The ranges are wide. Whatever can reach the app from inside them is trusted to say who the caller is. Keep the app reachable only through the load balancer, and do not put other programs that you do not control inside the same virtual network.
  • If you put Azure Front Door in front of App Service, do not list its addresses: see the next section. For another front end that has few, stable addresses, list them as well; otherwise the service takes that front end as the caller and every visitor counts as one.
  • The caller is the address that the proxy wrote into X-Forwarded-For: with network.trustedProxyHops at its default of 1, the last entry. Addresses to its left are the caller's own claims and are ignored, so a visitor cannot choose its own address by sending the header, even a visitor whose own address is inside the listed private ranges. If you put another listed front end in front of App Service, set network.trustedProxyHops to 2, list the front end, and restrict the app so that only that front end can reach it. That has a price: with two hops, a visitor that connects from inside the listed ranges can choose the address it is counted as, once, and the limits per caller do not hold for it. More hops make it worse, so use no more than the chain has. An address that carries a port is read without the port.
  • After you deploy, check it on the running app: send requests from two different addresses and see that they are counted as two callers (one is not refused because of the other), and send a request with a forged X-Forwarded-For: 203.0.113.9 and see that the forged address is not the one counted.

Azure Front Door in front of App Service

Do not try to list the addresses of Front Door. There are hundreds of ranges (the service tag AzureFrontDoor.Backend), they change, the service accepts at most 32 entries, and other Azure customers use the same addresses (origin-security). The service recognizes your Front Door by proof instead:

  1. Lock the web app to your Front Door with an access restriction (app-service-ip-restrictions): allow the service tag AzureFrontDoor.Backend with the header filters x-azure-fdid (the Front Door ID of your profile) and x-forwarded-host (your host names), and deny everything else. Azure then answers 403 to every other request, before the service sees it. This includes the azurewebsites.net address of the app and the default azurefd.net name of the Front Door.
  2. Tell the service in settings.json (the ranges are the three private ranges of App Service from the section above, and the hops stay at 1):

    "network": {
      "trustForwardedHeaders": true,
      "trustedProxies": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
      "trustedProxyHops": 1,
      "edge": {
        "mode": "azureFrontDoor",
        "frontDoorId": "<the Front Door ID of your profile>",
        "hosts": ["<the host name your visitors type>"]
      }
    }
    

    The service does not start if the ID is not written as the portal shows it, if the host list is empty, or if network.trustedProxyHops is not 1. The message says what to change.

  3. What the service then does with every request except the two health routes (/health/live and /health/ready, which the platform's own health check needs): it checks again that the connection comes from your web server, that there is exactly one X-Azure-FDID and that it is your ID, and that there is exactly one X-Forwarded-Host and that it is one of your host names. A request that fails is refused with 403 and BX6024, before the body is read, and uses nobody's allowance. If all is right, it removes the last entry of X-Forwarded-For (the address of Front Door itself, written by App Service) and then reads one hop as before: the caller is the address that Front Door saw, and everything to its left is the visitor's own claim.

What to know about it:

  • The service check is as strong as the Front Door ID staying private. The service cannot tell where a request came from; the lock in step 1 does. If the lock is missing and someone who knows the ID reaches the app directly, that person can choose the address it is counted as. Treat the ID like a password: keep it out of source control, pull requests, logs and messages; write it into settings.json only when you deploy, and do not share that file.
  • Check the lock often, not only once: a request with no headers to the azurewebsites.net address of the app, and another to the default azurefd.net name of the Front Door, must both be answered 403 (by Azure, with no BarcoderX code in the answer). Do it after every deploy and once a day.
  • Check the layout once on the running app. The service expects the visitor's address second from the right in X-Forwarded-For: Front Door writes it, and App Service then writes Front Door's own address. Send 30 requests through Front Door, each with a different forged X-Forwarded-For: 203.0.113.N: the later ones must be answered 429 (too many requests). If they are not, the layout is different from what the service expects, and the edge mode must not be used until that is understood.
  • Also check that two visitors on two networks are counted as two callers, and that a real browser through Front Door gets 200 or 401 and never 431: Front Door and App Service add headers of their own, and the service refuses more than 50 headers or 16 KB.
  • One-time proof of the lock (optional, recommended). Because other Azure customers share Front Door's addresses, create a second, throwaway Front Door profile that points at your app, and send a request through it: it must be answered 403, because its ID is not yours. Send a second one through it with a forged X-Azure-FDID: <your ID> header: it must also be answered 403. (Whether Front Door replaces or adds to a header that the visitor sent is not stated in the pages that were read; the service refuses a request that carries two ID values, so the second case is refused either way.) Delete the throwaway profile afterwards: a profile is billed until it is deleted.
  • International host names go in hosts in their xn-- form. A name with a port, a dot at the end or a list of names does not match.

Checking it

After you start the proxy and the service, check from another computer:

  1. curl https://labels.example.com/health/live answers {"status":"ok"}.
  2. curl https://labels.example.com/api/v1/meta/limits lists the limits of the service.
  3. Send a template and look at the picture, as in The label service.
  4. Send more requests in a minute than the limit of one caller. The answer is 429 with a Retry-After header. If the answer is 429 for a caller on its own after a single request, the service sees every caller as the proxy: check network.trustForwardedHeaders and network.trustedProxies.
  5. Look at the log of the service. It has one line for each request: status, route, sizes, time, the code of a problem and the trace id. It never has the content of a template.

What the service does by itself

Whatever the proxy does, the service keeps these limits, and you can read the numbers at /api/v1/meta/limits:

  • one request at a time for each caller; the whole template is read before a place for drawing is taken, within limits.bodyReadMilliseconds (5 seconds), so a slow sender holds no place for drawing (the server also stops a sender that sends fewer than 240 bytes a second on average once its first 5 seconds are over, whatever that setting says); and a place for drawing only while the label is laid out and drawn;
  • a pool of its own for the answers that wait for their readers, and the time it gives a reader to take an answer (5 seconds);
  • the connections of a caller (16 by default), except from a proxy that you list;
  • the requests of a caller in a minute, and of all callers together for the routes that draw;
  • the size of a template, the time of a request and the size of an answer.

How much memory to give the service

Three budgets can be full at the same time, and the memory of the host has to hold all of them, on top of what the runtime itself uses:

  • the renders: limits.memoryBudgetMegabytes (1,024 MB by default);
  • the answers that wait for their readers: limits.outputBudgetMegabytes (128 MB by default);
  • the templates that are being received: a quarter of limits.memoryBudgetMegabytes (256 MB by default).

At the defaults that is 1,024 + 128 + 256 = 1,408 MB, so give the service at least 2 GB, and more if you use the server garbage collector, which keeps memory the program has freed for longer. If you raise limits.maxBodyBytes for the web editor, raise limits.memoryBudgetMegabytes as well: it counts 60 times the body limit for each request, on top of its picture and its text.

One more amount is held outside these budgets for a moment: a caller that asks for printer commands as JSON (Accept: application/json) makes the JSON document in memory before it is counted in the pool of answers, which is about the size of the commands (at most about twice limits.maxCommandsBytes, which is 16 MB by default, in the worst case) for each request that asks for it at that moment. With the defaults, one caller makes one request at a time (limits.maxRequestsInFlightPerClient), so this is up to tens of megabytes per caller that asks, and it is given back as soon as the answer is counted or refused. A JSON answer larger than the whole pool is refused with BX6019 and no Retry-After; the plain text of the same commands always fits the pool.

A request for the pictures of single elements (POST /api/v1/render/elements) holds more memory than a picture. The worst request found, 64 filled and rounded elements of 40 millimeters at 300 dpi, allocated 299 to 319 MB over its life, and its memory peaked 136 MB above the start in a fresh process and up to 270 MB in one that had been running, because the collector lets garbage build up when it has been busy. The service assumes 350 MB for the engine, the encoder of the pictures and the answer, 16 MB more as room, and, as for every request, 60 times the body limit and 1.7 KB for each character of the label. At the defaults that is about 390 MB, which is more than one place holds (about 207 MB), so such a request takes two of the places. At the default budget (1,024 MB) there are four places, so while one request for elements runs, pictures are still drawn and a second request for elements can run; a third is refused at once with BX6006. A caller can also make only 6 requests for elements a minute by default (rateLimit.elementRequestsPerMinutePerClient), so one caller cannot keep the places for itself. With a smaller limits.memoryBudgetMegabytes a request for elements takes more of the places, or all of them; with a larger one there are more places and more of these requests run together. The figure is measured, not guessed: a test repeats the measure on every build and fails if the worst request allocates more than the figure.

What only the proxy can close

The service limits what one address can do, and since the template is read before a place for drawing is taken, a slow sender no longer holds the few places for drawing. It still cannot tell real callers apart when many addresses together are the problem. The proxy of this page is therefore required for a public service, not an extra. These gaps remain, and each was measured:

  • A slow sender still costs a connection for a few seconds. It holds its own caller place and one connection for at most limits.bodyReadMilliseconds (5 seconds), and is then stopped with BX6017. It holds no place for drawing, so ordinary callers are served meanwhile. A proxy that buffers the whole request body before it passes the request on takes even that cost away. The proxy_request_buffering on line of the nginx example and the request_buffers line of the Caddy example do that. Test it with a slow sender before you rely on it.
  • The total of 256 connections can still be filled by many addresses. The limit per address (16 by default) does not stop many addresses from taking all 256 connections together. A refused request now ends its connection at once: the answer is sent with Connection: close, the service waits one second for the rest of the body, and cuts the connection if it has not come. So a refusal no longer keeps its connection for several seconds, but enough addresses can still fill the total. Limit the connections of each address and the time of a request header at the proxy, as the examples do.
  • The quota of all callers is shared. Requests that draw from many addresses can use up the quota of all callers together (rateLimit.requestsPerMinuteAllClients), and a new caller is then refused with BX6014 although it did nothing wrong. Only a rate limit at the proxy can tell real callers apart.
  • One request at a time for each address. The service allows one request in flight and 16 connections for each caller address. Everyone behind one shared address (an office network or a mobile carrier) shares that one place and has to send labels one at a time. If your callers are behind shared addresses, raise limits.maxRequestsInFlightPerClient. A proxy does not help here, because it sees the same shared address; it only matters that the service reads the caller address from the proxy (network.trustForwardedHeaders) when the proxy sits in front of it.

Not decided yet

  • The address of the documentation of the problem codes. The type member of a problem document is an address under docs.barcoderx.example. The real domain is not decided yet, and nothing follows the address.
  • The evaluation mark and the license. Until a license is registered, every picture and every set of commands carries the evaluation mark.

BarcoderX is a product of P4 Software.

Was this page helpful?