Domains & Labels Design Notes

Loc'd basically does "virtual-host" HTTP routing of local requests servers running on various local ports. Those servers are run as agents though LaunchD (LaunchD calls it's user-space daemons agents). Loc'd has facilities to create these agents, assign them ports, and start them on-demand when it receives a request for them.

Loc'd relies on DNSMasq to point local DNS queries at it for one or more "fake" top-level domains (TLDs), then uses the HTTP Host header to figure out what agent to send it to. Right now we're using test as the default TLD, and I'll use it in these examples.

So, the Loc'd proxy receives a request that is supposed to go to an agent A that looks like

<subdomian>.test/<path>

I've been using a

<service_name>.<project_name>[.<project_owner>].test

format, such as

yard.www-rails.beiarea.test

# implied owner = me
yard.qb.test

but I'd pretty much like to allow the subdomain to be structured however users want, and switch the TLD or use multiple, though that doesn't really matter for what we're talking about here... all that matters is it has a valid unique subdomain.

Ok, so agents are identified by a label, which is usually structured as a Java-namespace-style "reverse subdomain", like

com.github.facebook.watchman
com.dropbox.DropboxMacUpdate.agent
keybase.kbfs
homebrew.mxcl.postgresql

and are suffixed with .plist for their LaunchD property list file. I'm not sure if the domain-ish format is required or enforced by LaunchD at some point, but it fits well with our subdomain identifiers, which is great.

As you can see, people have taken slightly different approaches:

# Ex 1. <project_host>.<project_owner>.<project_name>
com.github.facebook.watchman

# Ex 2. <owner_domain>.<service_name>.agent
com.dropbox.DropboxMacUpdate.agent

# Ex 3. <product_name>.<service_name>
keybase.kbfs

# Ex 4. <project_name>.<project_owner>.<service_name>
homebrew.mxcl.postgresql

Some options I've thought of:

Opt 1 Project-host-spaced like (Ex 1)

<project_host>.<project_owner>.<project_name>.<reversed_subdomain...>
com.github.nrser.locd.qb.yard

Ugh, way too long. 不要.

Opt 2 Can make it shorter by using my domain like (Ex 2)

<owner_domain>.<project_name>.<reversed_subdomain...>
com.nrser.locd.qb.yard
  • Plus
    1. Not too long
    2. Totally unique
  • Minus
    1. Still kinda long
    2. May also need a part do differentiate user agents and Loc'd system agents? So that would extend it...

Opt 3 Project name-only like (Ex 3)

<project_name>.<reversed_subdomain...>
locd.qb.yard
  • Plus
    1. Nice and short
  • Minus
    1. Not really "fully qualified", but doesn't seem like a big issues

Opt 4.1 Full reversed domain

<TLD>.<reversed_subdomain...> (really, just the reversed domain)
test.qb.yard

  • Plus

    1. Really strait-forward and simple:

      1. Receive request to domain D
      2. For reverse domain D_r see if <D_r>.plist exists
2.  Gives direct and complete control to the user
  • Minus
    1. Prevents (or at least makes much more awkward) to serve on multiple TLDs
2.  Need to read the `.plist` files when figuring out if a `.plist` is associated with Loc'd or not since there's no guaranteed indication in the label.

3.  Annoying that the label and domain are reversed, have to remember which you're using and reverse in your head when typing.

    This is probably my biggest issue with this one.

Opt 4.2 Full domain (not reversed)

<subdomain...>.<TLD> (really, just the domain)
yard.qb.test
yard.qb.localhost

  • Plus

    1. Everything from (Opt 4.1)
    2. Has the same order as the URL

  • Minus

    1. Differs from the convention
    2. Doesn't sort naturally

I think (Opt 4.2) is the winner

Simplicity and power. No extra explaining or translating of anything.