[policy] rename policy.lua to init.lua

CHANGELOG.md

@@ -49,6 +49,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Renamed `apicast/policy/policy.lua` to `apicast/policy.lua` [PR #569](https://github.com/3scale/apicast/pull/569)
 - Sandbox loading policies [PR #566](https://github.com/3scale/apicast/pull/566)
 - Extracted `usage` and `mapping_rules_matcher` modules so they can be used from policies [PR #580](https://github.com/3scale/apicast/pull/580)
+- Renamed all `apicast/policy/*/policy.lua` to `apicast/policy/*/init.lua` to match Lua naming [PR #579](https://github.com/3scale/apicast/pull/579)
 
 ## [3.2.0-alpha2] - 2017-11-30
 

doc/policies.md

@@ -15,7 +15,7 @@ APIcast.
 ## Policies
 
 A policy tells APIcast what it should do in each of the nginx phases: `init`,
-`init_worker`, `rewrite`, `access`, `balancer`, `header_filter`, `body_filter`,
+`init_worker`, `rewrite`, `access`,`content`, `balancer`, `header_filter`, `body_filter`,
 `post_action`, and `log`.
 
 Policies can share data between them. They do that through what we call the
@@ -35,6 +35,7 @@ policy B. When APIcast receives a request, it will check the policy chain
 described to see what it should run on each phase:
 - rewrite: execute the function policy A provides for this phase.
 - access: execute the function policy B provides for this phase.
+- content: do nothing. Neither policy A nor B describe what to do.
 - balancer: do nothing. Neither policy A nor B describe what to do.
 - header_filter: execute first the function policy A provides for this phase
   and then the function policy B provides for this phase. Remember that policy
@@ -68,9 +69,45 @@ matching, authorization and reporting against 3scale backend, etc.). In the
 future, this policy will be split and each of the resulting policies will be
 replaceable with custom ones.
 
-
 ## Write your own policy
 
+### Policy structure
+
+Policy is expected to have some structure, so APIcast can find it. Minimal policy structure consists of two files: `init.lua` and `apicast-manifest.json`.
+
+Custom policies are expected to be on following paths:
+
+* `APICAST_DIR/policies/${name}/${version}/`
+
+And builtin ones also on:
+
+* `APICAST_DIR/src/apicast/policy/${name}/`
+
+All files in the policy directory are namespaced, so you can vendor dependencies.  Consider following structure:
+
+```
+APICAST_DIR/policies/my_stuff/1.0/
+APICAST_DIR/policies/my_stuff/1.0/init.lua
+APICAST_DIR/policies/my_stuff/1.0/my_stuff.lua
+APICAST_DIR/policies/my_stuff/1.0/vendor/dependency.lua
+APICAST_DIR/policies/my_stuff/1.0/apicast-manifest.json
+```
+
+First file to be loaded will be `init.lua`. That is the only Lua file APIcast cares about.
+For better code organization we recommend that file to have just very simple implementation like:
+
+```lua
+return require('my_stuff')
+```
+
+And actually implement everything in `my_stuff.lua`. This makes the policy file easier to find by humans.
+
+Lets say the policy needs some 3rd party dependency. Those can be put anywhere in the policy structure and will be available. Try to imagine it as UNIX `chroot`. So for example `require('vendor/dependency')` will load `APICAST_DIR/policies/my_stuff/1.0/vendor/dependency.lua` when loading your policy.
+
+The policy has access to only code it provides and shared code in `APICAST_DIR/src/`.
+
+### Policy code
+
 To write your own policy you need to write a Lua module that instantiates a
 [Policy](../gateway/src/apicast/policy.lua) and defines a method for
 each of the phases where it needs to execute something.
@@ -158,7 +195,7 @@ policies can be configured:
       "proxy":{
         "policy_chain":[
           {
-            "name":"apicast.policy.cors",
+            "name":"cors", "version": "builtin",
             "configuration":{
               "allow_headers":["X-Custom-Header-1","X-Custom-Header-2"],
               "allow_methods":["POST","GET","OPTIONS"],
@@ -167,7 +204,7 @@ policies can be configured:
             }
           },
           {
-            "name":"apicast.policy.apicast"
+            "name":"apicast", "version": "builtin",
           }
         ]
       }

examples/custom-module/README.md

@@ -15,7 +15,7 @@ There is another example of custom module implementation for IP blacklisting in
 APICAST_MODULE=$(pwd)/verbose.lua ../../bin/apicast -c $(pwd)/../configuration/local.json
 ```
 
-This starts APIcast with module `verbose.lua` instead of the default [`apicast.lua`](../../gateway/src/apicast/policy/apicast/policy.lua). Local configuration file is used, so no 3scale account is needed.
+This starts APIcast with module `verbose.lua` instead of the default [`apicast.lua`](../../gateway/src/apicast/policy/apicast/apicast.lua). Local configuration file is used, so no 3scale account is needed.
 
 ## Testing
 

gateway/src/apicast/loader.lua

@@ -8,7 +8,9 @@
 -- Policies can be packaged as `some_name/policy.lua` so the directory also contains the JSON spec.
 
 local loadfile = loadfile
-local find = string.find
+local sub = string.sub
+
+local policy_loader = require 'apicast.policy_loader'
 
 local map = {
   ['apicast'] = 'apicast.policy.apicast'
@@ -24,28 +26,21 @@ local function loader(name, path)
   return file, err
 end
 
---- Try to load a policy. Policies can have a `.policy` suffix.
-local function policy_loader(name, path)
-  if not find(name, '.policy.', 1, true) then return end
-
-  local policy = name .. '.policy'
-
-  return loader(policy, path or package.path)
-end
-
 --- Searcher has to return the loader or an error message.
-local function policy_searcher(name, path)
-  local found, err = policy_loader(name, path)
+local function policy_searcher(name)
+  if sub(name, 1, 15) == 'apicast.policy.' then
+    local mod = policy_loader:pcall(sub(name, 16), 'builtin')
 
-  return found or err
+    if mod then return function () return mod end end
+  end
 end
 
 local function prefix_loader(name, path)
   local prefixed = 'apicast.' .. name
   local found, err = loader(prefixed, path)
 
   if not found then
-    found = policy_loader(prefixed, path)
+    found = policy_searcher(prefixed)
   end
 
   if found then
@@ -60,7 +55,7 @@ local function rename_loader(name, path)
   local found, err = loader(new, path)
 
   if not found then
-    found = policy_loader(new, path)
+    found = policy_searcher(new)
   end
 
   if found then

gateway/src/apicast/policy/apicast/init.lua

@@ -0,0 +1 @@
+return require('apicast')

gateway/src/apicast/policy/caching/init.lua

@@ -0,0 +1 @@
+return require('caching')

gateway/src/apicast/policy/cors/init.lua

@@ -0,0 +1 @@
+return require('cors')

gateway/src/apicast/policy/echo/init.lua

@@ -0,0 +1 @@
+return require('echo')

gateway/src/apicast/policy/find_service/init.lua

@@ -0,0 +1 @@
+return require('find_service')

gateway/src/apicast/policy/headers/init.lua

@@ -0,0 +1 @@
+return require('headers')

gateway/src/apicast/policy/load_configuration/init.lua

@@ -0,0 +1 @@
+return require('load_configuration')

gateway/src/apicast/policy/local_chain/init.lua

@@ -0,0 +1 @@
+return require('local_chain')

gateway/src/apicast/policy/phase_logger/init.lua

@@ -0,0 +1 @@
+return require('phase_logger')

gateway/src/apicast/policy/upstream/init.lua

@@ -0,0 +1 @@
+return require('upstream')

gateway/src/apicast/policy/url_rewriting/init.lua

@@ -0,0 +1 @@
+return require('url_rewriting')

gateway/src/apicast/policy_loader.lua

@@ -13,6 +13,7 @@ local getenv = os.getenv
 local insert = table.insert
 local setmetatable = setmetatable
 local concat = table.concat
+local pcall = pcall
 
 local _G = _G
 local _M = {}
@@ -274,7 +275,17 @@ function _M:call(name, version, dir)
 
   -- passing the "exclusive" flag for the require so it does not fallback to native require
   -- it should load only policies and not other code and fail if there is no such policy
-  return loader('policy', true)
+  return loader('init', true)
+end
+
+function _M:pcall(name, version, dir)
+  local ok, ret = pcall(self.call, self, name, version, dir)
+
+  if ok then
+    return ret
+  else
+    return nil, ret
+  end
 end
 
 return setmetatable(_M, { __call = _M.call })

spec/fixtures/policies/test/1.0.0-0/init.lua

@@ -0,0 +1 @@
+return require('test')

spec/policy_loader_spec.lua

@@ -17,8 +17,8 @@ describe('APIcast Policy Loader', function()
       local ok, ret = pcall(_M.call, _M, 'unknown', '0.1')
 
       assert.falsy(ok)
-      assert.match([[module 'policy' not found:
-%s+no file '%g+/gateway/policies/unknown/0.1/policy.lua']], ret)
+      assert.match([[module 'init' not found:
+%s+no file '%g+/gateway/policies/unknown/0.1/init.lua']], ret)
     end)
 
     it('loads two instances of the same policy', function()
@@ -41,4 +41,19 @@ describe('APIcast Policy Loader', function()
       assert.are.same({ '2.0 dependency' }, test2.dependency)
     end)
   end)
+
+  describe(':pcall', function()
+    it('returns the existing module', function()
+      assert(_M:call('apicast'))
+    end)
+
+    it('returns nil and error for invalid module', function()
+      local ok, err = _M:pcall('invalid', '0.1')
+
+      assert.is_nil(ok)
+      assert.is_string(err)
+      assert.match([[module 'init' not found:
+%s+no file '%g+/gateway/policies/invalid/0.1/init.lua']], err)
+    end)
+  end)
 end)