github.com/iron-io/functions@v0.0.0-20180820112432-d59d7d1c40b2/docs/operating/extending.md (about)

     1  # Extending IronFunctions
     2  
     3  IronFunctions is extensible so you can add custom functionality and extend the project without needing to modify the core.
     4  
     5  There are multiple ways to extend the functionality of IronFunctions.
     6  
     7  1. Listeners - listen to API events such as a route getting updated and react accordingly.
     8  1. Middleware - a chain of middleware is executed before an API handler is called.
     9  1. Add API Endpoints - extend the default IronFunctions API.
    10  
    11  ## Listeners
    12  
    13  Listeners are the main way to extend IronFunctions.
    14  
    15  The following listener types are supported:
    16  
    17  * App Listeners - [GoDoc](https://godoc.org/github.com/iron-io/functions/api/server#AppListener)
    18  * Runner Listeners - [GoDoc](https://godoc.org/github.com/iron-io/functions/api/server#RunnerListener)
    19  
    20  ### Creating a Listener
    21  
    22  You can easily use app and runner listeners by creating a struct with valid methods satisfying the interface for the respective listener and adding it to the IronFunctions API
    23  
    24  Example:
    25  
    26  ```
    27  package main
    28  
    29  import (
    30      "context"
    31  
    32      "github.com/iron-io/functions/api/server"
    33      "github.com/iron-io/functions/api/models"
    34  )
    35  
    36  type myCustomListener struct{}
    37  
    38  func (c *myCustomListener) BeforeAppCreate(ctx context.Context, app *models.App) error { return nil }
    39  func (c *myCustomListener) AfterAppCreate(ctx context.Context, app *models.App) error { return nil }
    40  
    41  func (c *myCustomListener) BeforeAppUpdate(ctx context.Context, app *models.App) error { return nil }
    42  func (c *myCustomListener) AfterAppUpdate(ctx context.Context, app *models.App) error { return nil }
    43  
    44  func (c *myCustomListener) BeforeAppDelete(ctx context.Context, app *models.App) error { return nil }
    45  func (c *myCustomListener) BeforeAppDelete(ctx context.Context, app *models.App) error { return nil }
    46  
    47  function main () {
    48      srv := server.New(/* Here all required parameters to initialize the server */)
    49  
    50      srv.AddAppListener(myCustomListener)
    51  
    52      srv.Run()
    53  }
    54  ```
    55  
    56  ## Middleware
    57  
    58  Middleware enables you to add functionality to every API request. For every request, the chain of Middleware will be called
    59  in order, allowing you to modify or reject requests, as well as write output and cancel the chain.
    60  
    61  NOTES:
    62  
    63  * middleware is responsible for writing output if it's going to cancel the chain.
    64  * cancel the chain by returning an error from your Middleware's Serve method.
    65  
    66  See examples of this in [examples/middleware/main.go](../../examples/middleware/main.go).
    67  
    68  ## Adding API Endpoints
    69  
    70  You can add API endpoints to the IronFunctions server by using the `AddEndpoint` and `AddEndpointFunc` methods.
    71  
    72  See examples of this in [examples/extensions/main.go](../../examples/extensions/main.go).