Events and Listeners
Gkernel is event-based framework, so Event and Listener are very important concepts in Gkernel's architecture.
Event is an object that represents some happening inside application during it's operation. Every event have to implement interface:
type Event interface {
StopPropagation()
IsPropagationStopped() bool
}
To process Event Listener object is used. Listener is just a function with one argument, and type of that argument have to correspond to Event's type.
There can be multiple listeners for one event, this is called Listeners Chain and Event is propagating through that chain.
Order of Listeners in chain is determined by Listeners priority (the lower the priority first).
Event's propagation inside the Listeners Chain can be stopped by calling StopPropagation()
method of the Event object.
Main way to register Listened is to declare it in Configuration file:
IndexController:privatePage:
url: "/private-page"
methods: ["GET"]
controller: "IndexController:PrivatePage"
event_listeners:
- {event: kernelEvent.RequestReceived, listener: "AuthService:RedirectToLoginIfNotAuthenticated", priority: 41}
This example shows registration of Listener for RequestReceived
Event, with priority 41
and
where Listener is method RedirectToLoginIfNotAuthenticated
from AuthService
Service.
Event types
Gkernel's events can be application level and request level.
Application level events
Application level events are used to manage request-processing flow.
There are next application level events:
ApplicationLaunched
Is being dispatched after application started, and configured but before it started to listen it's port. Can be used to establish DB connection, cache warming, etc.
ApplicationTermination
Is being dispatched during application shut down process. Can be used to close DB connections, exporting of some cached data, etc.
Application level events has next methods:
StopPropagation()
- to stop Event's propagation inside Listeners ChainIsPropagationStopped() bool
- returns if propagation of Event was stoppedGetContainer() *gioc.Container
- returns DI Container object used by Application.
Application level events has next attributes:
Errors *[]error
- slice of errors occurred during application shutdown process
Request level events
There are next request level events:
RequestReceived
Is being dispatched after request was received by framework but before it was passed to controller. Can be used to read user's session from the storage, for authentification & authorization, etc.
RequestReceived
Event has next methods:
StopPropagation()
- to stop Event's propagation inside Listeners ChainIsPropagationStopped() bool
- returns if propagation of Event was stoppedGetRequest() *http.Request
- returns Request objectRequestContextAppend(key, val interface{})
- appends provided val object to Request's contextGetResponseWriter() http.ResponseWriter
- returns ResponseWriter object associated with current RequestGetResponse() response.Response
- gets Response object provided to this Event. InitiallyRequestReceived
Event has no Response (method returnsnil
)SetResponse(responseObj response.Response)
- stops Event's propagation and sends provided Response to user.
RequestProcessed
Is being dispatched after Controller has processed Request. Contains Response object returned from Controller.
RequestProcessed
Event has next methods:
StopPropagation()
- to stop Event's propagation inside Listeners ChainIsPropagationStopped() bool
- returns if propagation of Event was stoppedGetRequest() *http.Request
- returns Request objectRequestContextAppend(key, val interface{})
- appends provided val object to Request's contextGetResponseWriter() http.ResponseWriter
- returns ResponseWriter object associated with current RequestGetResponse() response.Response
- gets Response object provided to this Event. Initially this will be Response returned by ControllerSetResponse(responseObj response.Response)
- sets Response object. Notice: unlikeRequestReceived.SetResponse()
this method does not stop Event's propagation
ResponseBeforeSend
Is being dispatched after RequestProcessed
Event was processed. Can modify Response but can not replace it with new object.
ResponseBeforeSend
Event has next methods:
StopPropagation()
- to stop Event's propagation inside Listeners ChainIsPropagationStopped() bool
- returns if propagation of Event was stoppedGetRequest() *http.Request
- returns Request objectRequestContextAppend(key, val interface{})
- appends provided val object to Request's contextGetResponseWriter() http.ResponseWriter
- returns ResponseWriter object associated with current RequestGetResponse() response.Response
- gets Response object
RequestTermination
Is being dispatched after Response was sent to user. Can be used for logs exporting and others after-request activities.
RequestTermination
Event has next methods:
StopPropagation()
- to stop Event's propagation inside Listeners ChainIsPropagationStopped() bool
- returns if propagation of Event was stoppedGetRequest() *http.Request
- returns Request objectGetResponse() response.Response
- gets Response object
RuntimeError
In case of panic during Request processing
Gkernel automatically recovers that panic, creates RuntimeError
object to represent that panic and dispatches RuntimeError.
RuntimeError
Event has next methods:
StopPropagation()
- to stop Event's propagation inside Listeners ChainIsPropagationStopped() bool
- returns if propagation of Event was stoppedGetRequest() *http.Request
- returns Request objectRequestContextAppend(key, val interface{})
- appends provided val object to Request's contextGetResponseWriter() http.ResponseWriter
- returns ResponseWriter object associated with current RequestGetResponse() response.Response
- gets Response object provided to this Event. InitiallyRuntimeError
Event has no Response (method returnsnil
)SetResponse(responseObj response.Response)
- stops Event's propagation and sends provided Response to user.GetError() *kernelError.RuntimeError
- returnsRuntimeError
object that represents recovered panic