locd 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eb0dc7c5d3b58d3a71a6f37ca805ad663a503d47
+  data.tar.gz: 0c4c9fe5124b32cdc7774b956bc44b95e80891c5
+SHA512:
+  metadata.gz: 51ec7cb0807e43bebe247e25854e8a2037f524d542b7d55bd6f40433704e3c354c4859335b5c48b72a908dca41fec8f56ccad955bd65a844a6d9e13269ff886b
+  data.tar.gz: e9e9309a808d16576fc38826a73b6f9034ce870be0b34871f57c360d398d736e61a9508ac2fb46a68f8e6c07925d38e8af334303f8c3e942b6ae4521ba992d7e

data/.gitignore

@@ -0,0 +1,108 @@
+##############################################################################
+# BEGIN Ruby.gitingore
+#
+# General Git ignore file for Ruby, including support for:
+# 
+# -   Bundler
+# -   RDoc and Yard
+# -   RBEnv and RVM
+# -   DotEnv (optional)
+# 
+# Additional support is available in separate ignore files:
+# 
+# -   Gem.gitignore (for gem source directories)
+# -   Rails.gitignore
+# -   RubyMotion.gitignore
+# 
+
+/*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, add `Gem.gitignore`
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+#
+# END Ruby.gitingore
+##############################################################################
+##############################################################################
+# BEGIN Gem.gitingore
+#
+/Gemfile.lock
+/.ruby-version
+/.ruby-gemset
+#
+# END Gem.gitingore
+##############################################################################
+##############################################################################
+# BEGIN Global/macOS.gitingore
+#
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+#
+# END Global/macOS.gitingore
+##############################################################################
+##############################################################################
+# BEGIN QB.gitingore
+#
+# generated qb playbooks
+.qb-playbook.yml
+
+# ansible retry files
+.qb-playbook.retry
+
+# error logs
+ansible-error.log
+#
+# END QB.gitingore
+##############################################################################
+!/doc/
+/doc/site/

data/.gitmodules

@@ -0,0 +1,9 @@
+[submodule "dev/packages/gems/nrser"]
+	path = dev/packages/gems/nrser
+	url = git@github.com:nrser/nrser.rb
+[submodule "dev/packages/gems/cmds"]
+	path = dev/packages/gems/cmds
+	url = git@github.com:nrser/cmds.git
+[submodule "dev/packages/gems/atli"]
+	path = dev/packages/gems/atli
+	url = git@github.com:nrser/atli.git

data/.qb-options.yml

@@ -0,0 +1,4 @@
+---
+qb/gem/new:
+  is-project: true
+  hub: true

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.4
+before_install: gem install bundler -v 1.16.1

data/.yardopts

@@ -0,0 +1,7 @@
+--markup-provider commonmarker
+--markup markdown
+--plugin yard-commonmarker
+--output-dir doc/site
+-
+doc/files/**/*.md
+README.md

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# gem 'nrser', path: './dev/packages/gems/nrser'
+# gem 'cmds', path: './dev/packages/gems/cmds'
+# gem 'atli', path: './dev/packages/gems/atli'
+
+# Specify your gem's dependencies in locd.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 nrser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,72 @@
+Loc'd
+==============================================================================
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/locd`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+
+-----------------------------------------------------------------------------
+Prerequisites
+-----------------------------------------------------------------------------
+
+1.  Homebrew
+
+2.  DNSMasq
+    
+    1.  Install DNSMasq
+    
+            brew install dnsmasq
+        
+    2.  Create resolver file for `test` domain
+        
+            sudo mkdir /etc/resolver/
+            sudo echo "nameserver 127.0.0.1" > /etc/resolver/test
+    
+    3.  Edit `/usr/local/etc/dnsmasq.conf` to contain the lines:
+    
+            strict-order
+            address=/.test/127.0.0.1
+            listen-address=127.0.0.1
+        
+    4.  Edit your network settings to put `127.0.0.1` first in DNS list
+    
+    5.  Start DNSMasq service
+    
+            sudo brew services start dnsmasq
+    
+    Ref: https://gist.github.com/ogrrd/5831371
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'locd'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install locd
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/locd.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+0.1.3

data/config/default.yml

@@ -0,0 +1,24 @@
+locd:
+  home: ~/.locd
+  bin: locd
+  
+  namespace:
+    label: com.nrser.locd
+    env: LOCD
+    
+  proxy:
+    port: 8888
+    bind: 127.0.0.1
+  
+  rotate_logs:
+    start_interval:
+      minute: 0
+    
+  agent:
+    config_key: locd_config
+  
+  site:
+    bind: 127.0.0.1
+    ports:
+      start: 55000
+      end: 56000

data/doc/files/design/domains_and_labels.md

@@ -0,0 +1,117 @@
+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.

data/doc/files/topics/agents.md

@@ -0,0 +1,16 @@
+launchd Agents
+==============================================================================
+
+"Agents" are what {file:doc/topics/launchd.md launchd} calls user (as opposed to system/root) jobs and services.
+
+Agents are defined in {file:doc/topics/plists.md} XML files in
+
+1.  `~/Library/LaunchAgents`
+    -   User-specific agents. They run as that user.
+    -   This is where Loc'd reads and writes its agents.
+        
+2.  `/Library/LaunchAgents`
+    -   Agents that still run as the current user but are shared by all users.
+    -   Loc'd ignores these at the moment - it doesn't read or write them. Maybe in the future if the need arises.
+
+Loc'd represents agents through the {Locd::Agent} class and it's subclasses.

data/doc/files/topics/launchd.md

@@ -0,0 +1,15 @@
+launchd & launchctl
+==============================================================================
+
+[launchd][] is the macOS service and job manager (as well as the init system, and probably a few other things as well... but we care about daemons and jobs).
+
+launchd calls jobs, services, etc. that run as the current user {file:doc/topics/agents.md}.
+
+Loc'd uses launchd agents to manage it's jobs and services, and interacts with launchd through the [launchctl][] command line interface, which is Ruby-wrapped by the {Locd::Launchctl} module.
+
+
+<!-- References & Further Reading: -->
+
+[launchd]: https://en.wikipedia.org/wiki/Launchd
+
+[launchctl]: https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man1/launchctl.1.html