github.com/System-Glitch/goyave/v2@v2.10.3-0.20200819142921-51011e75d504/docs/assets/js/13.770050f3.js

(window.webpackJsonp=window.webpackJsonp||[]).push([[13],{385:function(t,e,a){"use strict";a.r(e);var s=a(25),r=Object(s.a)({},(function(){var t=this,e=t.$createElement,a=t._self._c||e;return a("ContentSlotsDistributor",{attrs:{"slot-key":t.$parent.slotKey}},[a("h1",{attrs:{id:"multi-services"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#multi-services"}},[t._v("#")]),t._v(" Multi-services")]),t._v(" "),a("p"),a("div",{staticClass:"table-of-contents"},[a("ul",[a("li",[a("a",{attrs:{href:"#introduction"}},[t._v("Introduction")])]),a("li",[a("a",{attrs:{href:"#startup-hooks"}},[t._v("Startup hooks")])]),a("li",[a("a",{attrs:{href:"#start-the-server"}},[t._v("Start the server")]),a("ul",[a("li",[a("a",{attrs:{href:"#errors"}},[t._v("Errors")])])])]),a("li",[a("a",{attrs:{href:"#stop-the-server"}},[t._v("Stop the server")])]),a("li",[a("a",{attrs:{href:"#server-status"}},[t._v("Server status")])]),a("li",[a("a",{attrs:{href:"#maintenance-mode"}},[t._v("Maintenance mode")])])])]),a("p"),t._v(" "),a("h2",{attrs:{id:"introduction"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#introduction"}},[t._v("#")]),t._v(" Introduction")]),t._v(" "),a("p",[t._v("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.")]),t._v(" "),a("p",[t._v("All functions below are features that require the "),a("code",[t._v("goyave")]),t._v(" package to be imported.")]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("import")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"github.com/System-Glitch/goyave/v2"')]),t._v("\n")])])]),a("h2",{attrs:{id:"startup-hooks"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#startup-hooks"}},[t._v("#")]),t._v(" Startup hooks")]),t._v(" "),a("p",[t._v("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 "),a("strong",[t._v("before")]),t._v(" the "),a("code",[t._v("goyave.Start()")]),t._v(" call.")]),t._v(" "),a("h4",{attrs:{id:"goyave-registerstartuphook"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#goyave-registerstartuphook"}},[t._v("#")]),t._v(" goyave.RegisterStartupHook")]),t._v(" "),a("p",[t._v("Register a startup hook to execute some code once the server is ready and running.")]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",[t._v("Parameters")]),t._v(" "),a("th",[t._v("Return")])])]),t._v(" "),a("tbody",[a("tr",[a("td",[a("code",[t._v("hook func()")])]),t._v(" "),a("td",[a("code",[t._v("void")])])])])]),t._v(" "),a("p",[a("strong",[t._v("Example:")])]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[t._v("goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("RegsiterStartupHook")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("func")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n    goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("Logger"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("Println")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"Server ready."')]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("h4",{attrs:{id:"goyave-clearstartuphooks"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#goyave-clearstartuphooks"}},[t._v("#")]),t._v(" goyave.ClearStartupHooks")]),t._v(" "),a("p",[t._v("Clear all registered startup hooks. Useful when you are writing tests or developing a service able to restart your server multiple times.")]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",[t._v("Parameters")]),t._v(" "),a("th",[t._v("Return")])])]),t._v(" "),a("tbody",[a("tr",[a("td"),t._v(" "),a("td",[a("code",[t._v("void")])])])])]),t._v(" "),a("p",[a("strong",[t._v("Example:")])]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[t._v("goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("ClearStartupHooks")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("h2",{attrs:{id:"start-the-server"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#start-the-server"}},[t._v("#")]),t._v(" Start the server")]),t._v(" "),a("h4",{attrs:{id:"goyave-start"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#goyave-start"}},[t._v("#")]),t._v(" goyave.Start")]),t._v(" "),a("p",[t._v("Starts the server. This functions needs a route registrer function as a parameter. Learn more in the "),a("RouterLink",{attrs:{to:"/guide/basics/routing.html"}},[t._v("routing")]),t._v(" section."),a("br"),t._v("\nThe configuration is not reloaded if you call "),a("code",[t._v("Start")]),t._v(" multiple times. You can still reload the configuration with "),a("code",[t._v("config.Load()")]),t._v(" if you need it.\nThis operation is "),a("strong",[t._v("blocking")]),t._v(". Triggers a panic if the server is already running. Errors returned can be safely type-asserted to "),a("code",[t._v("*goyave.Error")]),t._v(".")],1),t._v(" "),a("table",[a("thead",[a("tr",[a("th",[t._v("Parameters")]),t._v(" "),a("th",[t._v("Return")])])]),t._v(" "),a("tbody",[a("tr",[a("td",[a("code",[t._v("routeRegistrer func(*goyave.Router)")])]),t._v(" "),a("td",[a("code",[t._v("error")])])])])]),t._v(" "),a("p",[a("strong",[t._v("Examples:")])]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("if")]),t._v(" err "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v(":=")]),t._v(" goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("Start")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("route"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("Register"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(";")]),t._v(" err "),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("!=")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token boolean"}},[t._v("nil")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n    os"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("Exit")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("err"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token operator"}},[t._v("*")]),t._v("goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("Error"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("ExitCode"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("p",[a("strong",[t._v("Running the server in the background:")])]),t._v(" "),a("p",[t._v("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 "),a("code",[t._v("goyave.Stop()")]),t._v(" to stop the server gracefully before exiting. Learn more in the next section.")]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("go")]),t._v(" goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("Start")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("route"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("Register"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("//...")]),t._v("\ngoyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("Stop")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("h3",{attrs:{id:"errors"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#errors"}},[t._v("#")]),t._v(" Errors")]),t._v(" "),a("p",[t._v("Errors generated byt the server itself (when calling "),a("code",[t._v("Start()")]),t._v(") are wrapped into an instance of "),a("code",[t._v("*goyave.Error")]),t._v(". This struct contains an exit code and the original error.")]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("type")]),t._v(" Error "),a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("struct")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n\tExitCode "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("int")]),t._v("\n\tErr      "),a("span",{pre:!0,attrs:{class:"token builtin"}},[t._v("error")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("p",[a("strong",[t._v("Exit codes:")])]),t._v(" "),a("ul",[a("li",[a("code",[t._v("2")]),t._v(": Panic (server already running, error when loading language files, etc)")]),t._v(" "),a("li",[a("code",[t._v("3")]),t._v(": Configuration is invalid")]),t._v(" "),a("li",[a("code",[t._v("4")]),t._v(": An error occurred when opening network listener")]),t._v(" "),a("li",[a("code",[t._v("5")]),t._v(": An error occurred in the HTTP server")])]),t._v(" "),a("h2",{attrs:{id:"stop-the-server"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#stop-the-server"}},[t._v("#")]),t._v(" Stop the server")]),t._v(" "),a("p",[t._v("When the running process receives a "),a("code",[t._v("SIGINT")]),t._v(" or a "),a("code",[t._v("SIGTERM")]),t._v(" signal, for example when you press "),a("code",[t._v("CTRL+C")]),t._v(" to interrupt the program, the server will shutdown gracefully, so you don't have to handle that yourself.")]),t._v(" "),a("p",[t._v("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 "),a("code",[t._v("goyave.Stop()")]),t._v(" is called. If the program exits because of an interruption signal, the server will shutdown gracefully.")]),t._v(" "),a("h4",{attrs:{id:"goyave-stop"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#goyave-stop"}},[t._v("#")]),t._v(" goyave.Stop")]),t._v(" "),a("p",[t._v("Stop the server gracefully without interrupting any active connections. Make sure the program doesn't exit and waits instead for Stop to return.")]),t._v(" "),a("p",[t._v("Stop does not attempt to close nor wait for hijacked connections such as WebSockets. The caller of "),a("code",[t._v("Stop")]),t._v(" should separately notify such long-lived connections of shutdown and wait for them to close, if desired.")]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",[t._v("Parameters")]),t._v(" "),a("th",[t._v("Return")])])]),t._v(" "),a("tbody",[a("tr",[a("td"),t._v(" "),a("td",[a("code",[t._v("void")])])])])]),t._v(" "),a("p",[a("strong",[t._v("Examples:")])]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[t._v("goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("Stop")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("h2",{attrs:{id:"server-status"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#server-status"}},[t._v("#")]),t._v(" Server status")]),t._v(" "),a("p",[t._v("The "),a("code",[t._v("goyave.IsReady()")]),t._v(" function lets you know if the server is running or not.")]),t._v(" "),a("p",[t._v("This function should not be used to wait for the server to be ready. Use a startup hook instead.")]),t._v(" "),a("h4",{attrs:{id:"goyave-isready"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#goyave-isready"}},[t._v("#")]),t._v(" goyave.IsReady")]),t._v(" "),a("p",[t._v("Returns true if the server is ready to receive and serve incoming requests.")]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",[t._v("Parameters")]),t._v(" "),a("th",[t._v("Return")])])]),t._v(" "),a("tbody",[a("tr",[a("td"),t._v(" "),a("td",[a("code",[t._v("bool")])])])])]),t._v(" "),a("p",[a("strong",[t._v("Example:")])]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[a("span",{pre:!0,attrs:{class:"token keyword"}},[t._v("if")]),t._v(" goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("IsReady")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("{")]),t._v("\n    goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),t._v("Logger"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("Println")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token string"}},[t._v('"Server is ready"')]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("}")]),t._v("\n")])])]),a("h2",{attrs:{id:"maintenance-mode"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#maintenance-mode"}},[t._v("#")]),t._v(" Maintenance mode")]),t._v(" "),a("p",[a("Badge",{attrs:{text:"Since v2.1.0"}})],1),t._v(" "),a("p",[t._v("On top of being able to start the server in maintenance mode using the "),a("code",[t._v("maintenance")]),t._v(" configuration entry, you can enable and disable this mode at runtime.")]),t._v(" "),a("div",{staticClass:"table"},[a("p",[a("a",{attrs:{href:"#goyave-enablemaintenance"}},[t._v("EnableMaintenance")]),t._v(" "),a("a",{attrs:{href:"#goyave-disablemaintenance"}},[t._v("DisableMaintenance")]),t._v(" "),a("a",{attrs:{href:"#goyave-ismaintenanceenabled"}},[t._v("IsMaintenanceEnabled")])])]),a("h4",{attrs:{id:"goyave-enablemaintenance"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#goyave-enablemaintenance"}},[t._v("#")]),t._v(" goyave.EnableMaintenance")]),t._v(" "),a("p",[t._v('Replace the main server handler with the "Service Unavailable" handler.')]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",[t._v("Parameters")]),t._v(" "),a("th",[t._v("Return")])])]),t._v(" "),a("tbody",[a("tr",[a("td"),t._v(" "),a("td",[a("code",[t._v("void")])])])])]),t._v(" "),a("p",[a("strong",[t._v("Example:")])]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[t._v("goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("EnableMaintenance")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("h4",{attrs:{id:"goyave-disablemaintenance"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#goyave-disablemaintenance"}},[t._v("#")]),t._v(" goyave.DisableMaintenance")]),t._v(" "),a("p",[t._v("Replace the main server handler with the original router.")]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",[t._v("Parameters")]),t._v(" "),a("th",[t._v("Return")])])]),t._v(" "),a("tbody",[a("tr",[a("td"),t._v(" "),a("td",[a("code",[t._v("void")])])])])]),t._v(" "),a("p",[a("strong",[t._v("Example:")])]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[t._v("goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("DisableMaintenance")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v("\n")])])]),a("h4",{attrs:{id:"goyave-ismaintenanceenabled"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#goyave-ismaintenanceenabled"}},[t._v("#")]),t._v(" goyave.IsMaintenanceEnabled")]),t._v(" "),a("p",[t._v("Returns true if the server is currently in maintenance mode.")]),t._v(" "),a("table",[a("thead",[a("tr",[a("th",[t._v("Parameters")]),t._v(" "),a("th",[t._v("Return")])])]),t._v(" "),a("tbody",[a("tr",[a("td"),t._v(" "),a("td",[a("code",[t._v("bool")])])])])]),t._v(" "),a("p",[a("strong",[t._v("Example:")])]),t._v(" "),a("div",{staticClass:"language-go extra-class"},[a("pre",{pre:!0,attrs:{class:"language-go"}},[a("code",[t._v("fmt"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("Println")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),t._v("goyave"),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(".")]),a("span",{pre:!0,attrs:{class:"token function"}},[t._v("IsMaintenanceEnabled")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v("(")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),a("span",{pre:!0,attrs:{class:"token punctuation"}},[t._v(")")]),t._v(" "),a("span",{pre:!0,attrs:{class:"token comment"}},[t._v("// false")]),t._v("\n")])])])])}),[],!1,null,null,null);e.default=r.exports}}]);