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
    2.  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.