gServ Plugins

#Using Plugins

Using Built-in Plugins

• Compression Supports Encoding-Type: gzip, compress
• CORS
• Client Caching (ETag Weak/Strong)

####Notes: The built-in plugins do not need to be registered - just declared inside the gServInstance.

---

Compression

The compression plugin will automatically compress any request and/or response when specified in the request header.

If the request contains Accept-Encoding header with one of: gzip, deflate, the response data will be compressed after all other processing.

If the request contains Content-Encoding header with one of: gzip, deflate, the request data will be decompressed before any processing.

---

CORS

Supports CORS (Cross Site Resource Sharing) specification. This allows the application to decide which clients can access a resource when the client is different from the resource.

The plugin adds a function the ServerConfig: cors(path, whichClients)

GServ has 3 ways to determine which clients are allowed access:

• allowAll(seconds) - allows all clients for a period of time
• whiteList(seconds, hostEntryMap) - each client on the whitelist can access the resource as specified in the host entry
• blackList(seconds, hostEntryMap) - no client on the blacklist will be able to access the resource in ways restricted by the host entry

HostEntryMap is a Map where key is the hostname or IP address and the value has properties:

• methods - a list of methods or '*' meaning all methods
• maxAge - how long this etag is valid
• customRequestHeaders - custom headers that are required

   def privateHostList = [
        "129.25.192.33": [
          methods             : ["GET", "PUT", "POST"],
          maxAge              : 7200
        ],
        "129.25.192.34": [
          methods             : ["GET", "PUT", "POST"],
          maxAge              : 7200
        ],
    ];

   def badHostList = [
        "hacker.com": [
          methods             : ["GET", "PUT", "POST"]
        ],
        "viruswritersguild.org": [
          methods             : ["GET", "PUT", "POST"]
        ]
    ];

gserv.plugins{
      plugin ( 'cors', [:] )
    }.http{
      // can be accessed by everyone
      cors('/public', allowAll(3600))

      // can ONLY be accessed by the hosts in the list
      cors('/private', whiteList(3600, privateHostList))

      // can be accessed by any host EXCEPT the ones in the list
      cors('/user/*', blackList(3600, badHostList))

      get('/public'){ ->
        write( "This is the public message.")
      }

      get('/private'){ ->
        write( "This is the private message.")
      }

      get('/user'){ ->
        write( "This is a user message.")
      }

    }.start(60001);

---

Client Caching (ETag-Weak/Strong)

The Client Caching plugin adds the ETAG header to the response. The Etag value is calculated by a user-defined function. To create an ETag value for a request, a function must be defined to calculate it. Below is an example:

gserv.plugins{
      plugin ( 'cors', [:] )
    }.http{

      get('/big/static/data/:id'){ id ->
        writeJson bigData(id)
      }

      /// Here we are not going to produce the BIG data, we are using the id 
      weakETag( "/big/static/data/:id"){ requestContext, List args ->
          Encoder.md5WithBase64(args.join('//').bytes)
      }

      get('/user/:id/status'){ id ->
        writeJson userStatus( id )
      }

      /// Here, because the data is more dynamic, we have to actually produce the data and then calc the ETag
      strongETag( "/user/:id/status"){requestContext, byte[] data ->
          //MD5 the user status data as the hash
          Encoder.md5WithBase64(data)
        }


}

Using Third-Party or Custom Plugins

The first thing we must do in order to use the plugin is register it with PluginMgr.

Register Plugin

        def pluginMgr = PluginMgr.instance()
        pluginMgr.register("coolPlugin", CoolPluginImpl.class)

####Notes: Use the public PluginMgr instance to register the plugins with gServ. Once gServ knows about the plugins, you can declare it for use in your gServInstance.

Declare the Plugin to be used with a particular gServInstance.

new GServ().plugins{
    plugins( "coolPlugin", [coolOption:true] )
}.http {
    cool() // call the cool() function which was added by the 'coolPlugin'
    get "/books/:id", { bookId -> 
        write "text/plain", "Getting book $bookId."
    } 
}.start(8080);

####Notes: To declare a plugin, use the 'plugins' function of GServ instance and pass the closure that defines the plugins for this gServInstance. In this closure, call the function 'plugin(name,options)' for each plugin you would like to use in that gServInstance. When using third-party plugins, be sure to read the plugin's documentation for any added Actions, Filters or new functions to the various definition closures (eg. ServerInstanceDef, ResourceActionDef, etc.)