Skip to content
Naasson Docs

Edge network

The Naasson edge is the routing layer that makes *.cloud.naasson.com resolvable to a service on someone’s laptop or home server, without anyone needing to open a port. This page explains the path a request takes.

The shape

                                ┌──────────────────────────────┐
                                │  cli.cloud.naasson.com (CDN) │
                                │  docs.cloud.naasson.com (CDN)│
                                │  apps.cloud.naasson.com (CDN)│
                                └──────────────────────────────┘
       Browser ─────────────────▶ resolves *.cloud.naasson.com
        │                              │
        │                              ▼ wildcard A record
        │                       89.169.130.203 (static IP)
        │                              │
        │                              ▼
        │                       ┌──────────────────┐
        │                       │ Network LB (NLB) │  TCP/443  TCP/8443
        │                       │ 3 listeners, L4  │
        │                       └────────┬─────────┘
        │                                │
        │                  ┌─────────────┴─────────────┐
        │                  │      Target group         │
        │                  │   3× edge instances       │
        │                  │   (Instance Group)        │
        │                  └─────┬────┬────┬───────────┘
        │                        │    │    │
        │                  ┌─────▼─┐ ┌▼──┐ ┌▼──┐   each runs naasson-edge
        │                  │ edge1 │ │e2 │ │e3 │   binary in Docker
        │                  └───┬───┘ └─┬─┘ └─┬─┘
        │                      │       │     │
        │                      └───┬───┴─────┘
        │                          │
        │                          ▼ YDB edge_connections table
        │                  ┌────────────────────┐
        │                  │ Which edge holds   │
        │                  │ a given agent_id?  │
        │                  └────────────────────┘
        │
        │  ── If route resolves: route → agent → host's local port ──
        ▼
   Your service on your host (no inbound port required)

The walk-through

When a browser hits my-app.cloud.naasson.com:

  1. DNS — *.cloud.naasson.com is a 60-second A record pointing at 89.169.130.203, the static IP of our Network Load Balancer.
  2. NLB — the load balancer is L4 TCP passthrough, not L7. It picks one of three healthy edge nodes (preemptible 2vCPU/2GB VMs in ru-central1-a) and forwards the TCP stream.
  3. Edge node — the edge binary terminates TLS using our wildcard *.cloud.naasson.com cert (Let’s Encrypt, auto-renewed) and looks up the requested FQDN in YDB tunnel_routes.
  4. Cross-edge — the route says “agent X handles this”. The edge that received the browser request may not be the one holding agent X’s persistent connection — agents stick to whatever node they first dialed. The receiving edge looks up edge_connections to find which sibling has the agent, then forwards the request over a private inter-edge channel on port :7443.
  5. Agent path — the holding edge writes the request into the agent’s persistent mTLS tunnel (a yamux multiplexed connection). The agent receives the frame, dials localhost:<target_port> on the host where it runs, copies bytes back.

The whole path adds about 80 milliseconds of overhead in the warm state — measured against a direct connection to the same host on a local network.

What this design buys you

  • No inbound port on the host. The agent dials outbound; the edge never connects to the host. Useful behind home NAT, mobile networks, corporate firewalls.
  • One TLS cert for everything. The single wildcard cert covers every issued FQDN; you never wait for a per-app cert.
  • Hot-swap edges. Because connection state is in YDB, killing one edge node doesn’t drop agents — the NLB routes future packets to surviving nodes, and the affected agents reconnect within a few seconds.
  • No app-side knowledge. Your localhost:8080 Express server doesn’t need to know it’s being proxied. The agent forwards plain TCP.

When the edge mints a session cookie (auth_mode=cookie), it scopes the cookie to the exact hostname — no Domain=.cloud.naasson.com. A session on my-app.cloud.naasson.com cannot be replayed on their-app.cloud.naasson.com, even though they share the wildcard cert.

If you’re building a programmatic client and don’t want cookies, set the route’s auth_mode to passthrough — the edge will skip auth and forward immediately.

Failure modes

  • Agent offline: the edge returns 404 route has no live agent (not a connection timeout — fail-fast).
  • Route doesn’t exist: 404 route not found.
  • Vanity collision on create: 409 — pick another name.
  • Edge node dies: NLB removes from rotation in ~5 seconds; agents on that node reconnect to a survivor.

See Security model for the trust boundaries.