Docs/cli help messages

Makefile

@@ -22,15 +22,15 @@ dev:
       echo "$$rock already installed, skipping" ; \
     fi \
 	done;
-	bin/kong config -e TEST
-	bin/kong config -e DEVELOPMENT
-	bin/kong db -c $(DEVELOPMENT_CONF) migrations:up
+	bin/kong config -c kong.yml -e TEST
+	bin/kong config -c kong.yml -e DEVELOPMENT
+	bin/kong migrations -c $(DEVELOPMENT_CONF) up
 
 clean:
 	@rm -f luacov.*
 	@rm -f $(DEVELOPMENT_CONF) $(TESTING_CONF)
 	@rm -rf nginx_tmp
-	@bin/kong db -c $(DEVELOPMENT_CONF) migrations:reset
+	@bin/kong migrations -c $(DEVELOPMENT_CONF) reset
 
 run:
 	@bin/kong start -c $(DEVELOPMENT_CONF)

bin/kong

@@ -1,32 +1,43 @@
 #!/usr/bin/env lua
 
+-- Kong CLI entry-point (bin/kong).
+--
+-- Kong's CLI is a set of small commands invoked by a global executable, this file.
+--
+-- All commands are invoked by this script, then parsed (arguments and options)
+-- by lapp (see http://lua-users.org/wiki/LappFramework).
+--
+-- This script is not parsed by lapp due to limitations of the said framework as it
+-- is currently implemented.
+
 local cutils = require "kong.cli.utils"
-local infos = cutils.get_infos()
+local infos = cutils.get_kong_infos()
 local commands = {
   db = "kong.cli.db",
   stop = "kong.cli.stop",
   quit = "kong.cli.quit",
   start = "kong.cli.start",
   reload = "kong.cli.reload",
   config = "kong.cli.config",
+  restart = "kong.cli.restart",
   version = "kong.cli.version",
   ["--version"] = "kong.cli.version",
-  restart = "kong.cli.restart"
+  migrations = "kong.cli.migrations"
 }
 
 local help_message = string.format([[
 Usage: kong <command>
 
-where <command> is one of:
-  start, stop, quit, restart, reload, config, db, version
+  where <command> is one of:
+    start, restart, reload, stop, quit, version
 
-kong --help            print this message
-kong <command> --help  print the help message of a command
+  kong --help            print this message
+  kong <command> --help  print the help message of a command
 
 %s@%s]], infos.name, infos.version)
 
+-- Determine validity of the given command
 local cmd = arg[1]
-
 if not cmd then
   print("Missing <command>\n\n"..help_message)
   os.exit(1)
@@ -38,4 +49,5 @@ elseif not commands[cmd] then
   os.exit(1)
 end
 
+-- Load and execute desired command
 require(commands[cmd])

kong-0.2.0-1.rockspec

@@ -48,6 +48,7 @@ build = {
     ["kong.cli.reload"] = "src/cli/reload.lua",
     ["kong.cli.restart"] = "src/cli/restart.lua",
     ["kong.cli.version"] = "src/cli/version.lua",
+    ["kong.cli.migrations"] = "src/cli/migrations.lua",
 
     ["kong.tools.utils"] = "src/tools/utils.lua",
     ["kong.tools.io"] = "src/tools/io.lua",

src/cli/config.lua

@@ -4,12 +4,14 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local IO = require "kong.tools.io"
 local args = require("lapp")(string.format([[
+For development purposes only.
+
 Duplicate an existing configuration for given environment.
 
 Usage: kong config [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
   -o,--output (default .)                  ouput
   -e,--env    (string)                     environment name
 ]], constants.CLI.GLOBAL_KONG_CONF))

src/cli/db.lua

@@ -1,25 +1,25 @@
 #!/usr/bin/env lua
 
 local Faker = require "kong.tools.faker"
-local Migrations = require "kong.tools.migrations"
-
 local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local IO = require "kong.tools.io"
 local lapp = require("lapp")
 local args = lapp(string.format([[
-Migrations, seeding of the DB.
+For development purposes only.
+
+Seed the database with random data or drop it.
 
 Usage: kong db <command> [options]
 
 Commands:
   <command> (string) where <command> is one of:
-                       migrations, migrations:up, migrations:down, migrations:reset, seed, drop
+                       seed, drop
 
 Options:
-  -c,--config (default %s) configuration file
-  -r,--random                              <seed>: flag to also insert random entities
-  -n,--number (default 1000)               <seed>: number of random entities to insert if --random
+  -c,--config (default %s) path to configuration file
+  -r,--random                              flag to also insert random entities
+  -n,--number (default 1000)               number of random entities to insert if --random
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 -- $ kong db
@@ -29,83 +29,8 @@ end
 
 local config_path = cutils.get_kong_config_path(args.config)
 local _, dao_factory = IO.load_configuration_and_dao(config_path)
-local migrations = Migrations(dao_factory, cutils.get_luarocks_install_dir())
-
-if args.command == "migrations" then
-
-  local migrations, err = dao_factory:get_migrations()
-  if err then
-    cutils.logger:error_exit(err)
-  elseif migrations then
-    cutils.logger:log(string.format(
-      "Executed migrations for %s on keyspace: %s:\n%s",
-      cutils.colors.yellow(dao_factory.type),
-      cutils.colors.yellow(dao_factory._properties.keyspace),
-      table.concat(migrations, ", ")
-    ))
-  else
-    cutils.logger:log(string.format(
-      "No migrations have been run yet for %s on keyspace: %s",
-      cutils.colors.yellow(dao_factory.type),
-      cutils.colors.yellow(dao_factory._properties.keyspace)
-    ))
-  end
-
-elseif args.command == "migrations:up" then
-
-  cutils.logger:log(string.format(
-    "Migrating %s keyspace: %s",
-    cutils.colors.yellow(dao_factory.type),
-    cutils.colors.yellow(dao_factory._properties.keyspace))
-  )
-
-  migrations:migrate(function(migration, err)
-    if err then
-      cutils.logger:error_exit(err)
-    elseif migration then
-      cutils.logger:success("Migrated up to: "..cutils.colors.yellow(migration.name))
-    else
-      cutils.logger:success("Schema already up to date")
-    end
-  end)
-
-elseif args.command == "migrations:down" then
-
-  cutils.logger:log(string.format(
-    "Rolling back %s keyspace: %s",
-    cutils.colors.yellow(dao_factory.type),
-    cutils.colors.yellow(dao_factory._properties.keyspace)
-  ))
-
-  migrations:rollback(function(migration, err)
-    if err then
-      cutils.logger:error_exit(err)
-    elseif migration then
-      cutils.logger:success("Rollbacked to: "..cutils.colors.yellow(migration.name))
-    else
-      cutils.logger:success("No migration to rollback")
-    end
-  end)
-
-elseif args.command == "migrations:reset" then
-
-  cutils.logger:log(string.format(
-    "Reseting %s keyspace: %s",
-    cutils.colors.yellow(dao_factory.type),
-    cutils.colors.yellow(dao_factory._properties.keyspace))
-  )
-
-  migrations:reset(function(migration, err)
-    if err then
-      cutils.logger:error_exit(err)
-    elseif migration then
-      cutils.logger:success("Rollbacked: "..cutils.colors.yellow(migration.name))
-    else
-      cutils.logger:success("Schema reseted")
-    end
-  end)
 
-elseif args.command == "seed" then
+if args.command == "seed" then
 
   -- Drop if exists
   local err = dao_factory:drop()

src/cli/migrations.lua

@@ -0,0 +1,106 @@
+#!/usr/bin/env lua
+
+local Migrations = require "kong.tools.migrations"
+local constants = require "kong.constants"
+local cutils = require "kong.cli.utils"
+local IO = require "kong.tools.io"
+local lapp = require("lapp")
+local args = lapp(string.format([[
+Kong datastore migrations.
+
+Usage: kong migrations <command> [options]
+
+Commands:
+  <command> (string) where <command> is one of:
+                       list, up, down, reset
+
+Options:
+  -c,--config (default %s) path to configuration file
+]], constants.CLI.GLOBAL_KONG_CONF))
+
+-- $ kong migrations
+if args.command == "migrations" then
+  lapp.quit("Missing required <command>.")
+end
+
+local config_path = cutils.get_kong_config_path(args.config)
+local _, dao_factory = IO.load_configuration_and_dao(config_path)
+local migrations = Migrations(dao_factory, cutils.get_luarocks_install_dir())
+
+if args.command == "list" then
+
+  local migrations, err = dao_factory:get_migrations()
+  if err then
+    cutils.logger:error_exit(err)
+  elseif migrations then
+    cutils.logger:log(string.format(
+      "Executed migrations for %s on keyspace %s:\n%s",
+      cutils.colors.yellow(dao_factory.type),
+      cutils.colors.yellow(dao_factory._properties.keyspace),
+      table.concat(migrations, ", ")
+    ))
+  else
+    cutils.logger:log(string.format(
+      "No migrations have been run yet for %s on keyspace: %s",
+      cutils.colors.yellow(dao_factory.type),
+      cutils.colors.yellow(dao_factory._properties.keyspace)
+    ))
+  end
+
+elseif args.command == "up" then
+
+  cutils.logger:log(string.format(
+    "Migrating %s keyspace: %s",
+    cutils.colors.yellow(dao_factory.type),
+    cutils.colors.yellow(dao_factory._properties.keyspace))
+  )
+
+  migrations:migrate(function(migration, err)
+    if err then
+      cutils.logger:error_exit(err)
+    elseif migration then
+      cutils.logger:success("Migrated up to: "..cutils.colors.yellow(migration.name))
+    else
+      cutils.logger:success("Schema already up to date")
+    end
+  end)
+
+elseif args.command == "down" then
+
+  cutils.logger:log(string.format(
+    "Rolling back %s keyspace: %s",
+    cutils.colors.yellow(dao_factory.type),
+    cutils.colors.yellow(dao_factory._properties.keyspace)
+  ))
+
+  migrations:rollback(function(migration, err)
+    if err then
+      cutils.logger:error_exit(err)
+    elseif migration then
+      cutils.logger:success("Rollbacked to: "..cutils.colors.yellow(migration.name))
+    else
+      cutils.logger:success("No migration to rollback")
+    end
+  end)
+
+elseif args.command == "reset" then
+
+  cutils.logger:log(string.format(
+    "Reseting %s keyspace: %s",
+    cutils.colors.yellow(dao_factory.type),
+    cutils.colors.yellow(dao_factory._properties.keyspace))
+  )
+
+  migrations:reset(function(migration, err)
+    if err then
+      cutils.logger:error_exit(err)
+    elseif migration then
+      cutils.logger:success("Rollbacked: "..cutils.colors.yellow(migration.name))
+    else
+      cutils.logger:success("Schema reseted")
+    end
+  end)
+
+else
+  lapp.quit("Invalid command: "..args.command)
+end

src/cli/quit.lua

@@ -4,12 +4,12 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local signal = require "kong.cli.utils.signal"
 local args = require("lapp")(string.format([[
-Graceful shutdown
+Graceful shutdown. Stop the Kong instance running in the configured 'nginx_working_dir' directory.
 
 Usage: kong stop [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 -- Check if running, will exit if not

src/cli/reload.lua

@@ -4,12 +4,14 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local signal = require "kong.cli.utils.signal"
 local args = require("lapp")(string.format([[
-Gracefully reload Kong applying any configuration changes (including nginx)
+Gracefully reload the Kong instance running in the configured 'nginx_working_dir'.
+
+Any configuration change will be applied.
 
 Usage: kong reload [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 signal.prepare_kong(args.config)

src/cli/restart.lua

@@ -4,10 +4,15 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local signal = require "kong.cli.utils.signal"
 local args = require("lapp")(string.format([[
+Restart the Kong instance running in the configured 'nginx_working_dir'.
+
+Kong will be shutdown before restarting. For a zero-downtime reload
+of your configuration, look at 'kong reload'.
+
 Usage: kong restart [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 if signal.is_running(args.config) then

src/cli/start.lua

@@ -4,10 +4,12 @@ local constants = require "kong.constants"
 local cutils = require "kong.cli.utils"
 local signal = require "kong.cli.utils.signal"
 local args = require("lapp")(string.format([[
+Start Kong with given configuration. Kong will run in the configured 'nginx_working_dir' directory.
+
 Usage: kong start [options]
 
 Options:
-  -c,--config (default %s) configuration file
+  -c,--config (default %s) path to configuration file
 ]], constants.CLI.GLOBAL_KONG_CONF))
 
 signal.prepare_kong(args.config)