github.com/System-Glitch/goyave/v2@v2.10.3-0.20200819142921-51011e75d504/docs_src/src/guide/advanced/multi-services.md (about)

     1  ---
     2  meta:
     3    - name: "og:title"
     4      content: "Multi-services - Goyave"
     5    - name: "twitter:title"
     6      content: "Multi-services - Goyave"
     7    - name: "title"
     8      content: "Multi-services - Goyave"
     9  ---
    10  
    11  # Multi-services
    12  
    13  [[toc]]
    14  
    15  ## Introduction
    16  
    17  Sometimes you need to run several services in the same executable. For example if you are hosting a websocket server on top of your web API. Goyave can be run in a goroutine and stopped on-demand.
    18  
    19  All functions below are features that require the `goyave` package to be imported.
    20  
    21  ``` go
    22  import "github.com/System-Glitch/goyave/v2"
    23  ```
    24  
    25  ## Startup hooks
    26  
    27  Startup hooks are function executed in a goroutine after the server finished initializing. This is especially useful when you want to start other services or execute specific commands while being sure the server is up and running, ready to respond to incoming requests. Startup hooks must be registered **before** the `goyave.Start()` call.
    28  
    29  #### goyave.RegisterStartupHook
    30  
    31  Register a startup hook to execute some code once the server is ready and running.
    32  
    33  | Parameters    | Return |
    34  |---------------|--------|
    35  | `hook func()` | `void` |
    36  
    37  **Example:**
    38  ``` go
    39  goyave.RegsiterStartupHook(func() {
    40      goyave.Logger.Println("Server ready.")
    41  })
    42  ```
    43  
    44  #### goyave.ClearStartupHooks
    45  
    46  Clear all registered startup hooks. Useful when you are writing tests or developing a service able to restart your server multiple times.
    47  
    48  | Parameters | Return |
    49  |------------|--------|
    50  |            | `void` |
    51  
    52  **Example:**
    53  ``` go
    54  goyave.ClearStartupHooks()
    55  ```
    56  
    57  ## Start the server
    58  
    59  #### goyave.Start
    60  
    61  Starts the server. This functions needs a route registrer function as a parameter. Learn more in the [routing](../basics/routing.html) section.  
    62  The configuration is not reloaded if you call `Start` multiple times. You can still reload the configuration with `config.Load()` if you need it.
    63  This operation is **blocking**. Triggers a panic if the server is already running. Errors returned can be safely type-asserted to `*goyave.Error`.
    64  
    65  | Parameters                            | Return  |
    66  |---------------------------------------|---------|
    67  | `routeRegistrer func(*goyave.Router)` | `error` |
    68  
    69  **Examples:**
    70  ``` go
    71  if err := goyave.Start(route.Register); err != nil {
    72      os.Exit(err.(*goyave.Error).ExitCode)
    73  }
    74  ```
    75  
    76  **Running the server in the background:**
    77  
    78  You can start the server in a goroutine. However, if you do this and the main goroutine terminates, the server will not shutdown gracefully and the program will exit right away. Be sure to call `goyave.Stop()` to stop the server gracefully before exiting. Learn more in the next section.
    79  ``` go
    80  go goyave.Start(route.Register)
    81  //...
    82  goyave.Stop()
    83  ```
    84  
    85  ### Errors
    86  
    87  Errors generated byt the server itself (when calling `Start()`) are wrapped into an instance of `*goyave.Error`. This struct contains an exit code and the original error.
    88  
    89  ``` go
    90  type Error struct {
    91  	ExitCode int
    92  	Err      error
    93  }
    94  ```
    95  
    96  **Exit codes:**
    97  - `2`: Panic (server already running, error when loading language files, etc)
    98  - `3`: Configuration is invalid
    99  - `4`: An error occurred when opening network listener
   100  - `5`: An error occurred in the HTTP server
   101  
   102  ## Stop the server
   103  
   104  When the running process receives a `SIGINT` or a `SIGTERM` signal, for example when you press `CTRL+C` to interrupt the program, the server will shutdown gracefully, so you don't have to handle that yourself.
   105  
   106  However, if you start the server in a goroutine, you have the responsibility to shutdown properly. If you exit the program manually or if the main goroutine terminates, ensure that `goyave.Stop()` is called. If the program exits because of an interruption signal, the server will shutdown gracefully.
   107  
   108  #### goyave.Stop
   109  
   110  Stop the server gracefully without interrupting any active connections. Make sure the program doesn't exit and waits instead for Stop to return.
   111  
   112  Stop does not attempt to close nor wait for hijacked connections such as WebSockets. The caller of `Stop` should separately notify such long-lived connections of shutdown and wait for them to close, if desired.
   113  
   114  | Parameters | Return |
   115  |------------|--------|
   116  |            | `void` |
   117  
   118  **Examples:**
   119  ``` go
   120  goyave.Stop()
   121  ```
   122  
   123  ## Server status
   124  
   125  The `goyave.IsReady()` function lets you know if the server is running or not.
   126  
   127  This function should not be used to wait for the server to be ready. Use a startup hook instead.
   128  
   129  #### goyave.IsReady
   130  
   131  Returns true if the server is ready to receive and serve incoming requests.
   132  
   133  | Parameters | Return |
   134  |------------|--------|
   135  |            | `bool` |
   136  
   137  **Example:**
   138  ``` go
   139  if goyave.IsReady() {
   140      goyave.Logger.Println("Server is ready")
   141  }
   142  ```
   143  
   144  ## Maintenance mode
   145  
   146  <p><Badge text="Since v2.1.0"/></p>
   147  
   148  On top of being able to start the server in maintenance mode using the `maintenance` configuration entry, you can enable and disable this mode at runtime.
   149  
   150  ::: table
   151  [EnableMaintenance](#goyave-enablemaintenance)
   152  [DisableMaintenance](#goyave-disablemaintenance)
   153  [IsMaintenanceEnabled](#goyave-ismaintenanceenabled)
   154  :::
   155  
   156  #### goyave.EnableMaintenance
   157  
   158  Replace the main server handler with the "Service Unavailable" handler.
   159  
   160  | Parameters | Return |
   161  |------------|--------|
   162  |            | `void` |
   163  
   164  **Example:**
   165  ``` go
   166  goyave.EnableMaintenance()
   167  ```
   168  
   169  #### goyave.DisableMaintenance
   170  
   171  Replace the main server handler with the original router.
   172  
   173  | Parameters | Return |
   174  |------------|--------|
   175  |            | `void` |
   176  
   177  **Example:**
   178  ``` go
   179  goyave.DisableMaintenance()
   180  ```
   181  
   182  #### goyave.IsMaintenanceEnabled
   183  
   184  Returns true if the server is currently in maintenance mode.
   185  
   186  | Parameters | Return |
   187  |------------|--------|
   188  |            | `bool` |
   189  
   190  **Example:**
   191  ``` go
   192  fmt.Println(goyave.IsMaintenanceEnabled()) // false
   193  ```