Capstan is a Golang web framework that shares some similarities with others in its segment.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

341 lines
9.3KB

  1. package capstan
  2. import (
  3. "net/http"
  4. "git.destrealm.org/go/capstan/config"
  5. "git.destrealm.org/go/capstan/mappers"
  6. "git.destrealm.org/go/capstan/render"
  7. "git.destrealm.org/go/capstan/session"
  8. "git.destrealm.org/go/logging"
  9. "github.com/gorilla/websocket"
  10. )
  11. type Application interface {
  12. AttachApplication(Application)
  13. DestroyApplication(Application)
  14. Application() *application
  15. LoadSession()
  16. BindGroup(path string) *RouterGroup
  17. Bind(controller Controller) error
  18. ReplaceController(from, to Controller) error
  19. ReplacePath(from, to string)
  20. Unmount(path string)
  21. UnmountController(controller Controller) error
  22. UnmountGroup(path string) error
  23. DefaultMiddleware()
  24. SetMiddleware(middleware ...func(http.Handler) http.Handler) Application
  25. SetDefaultRenderer(renderer render.Renderer) Application
  26. SetMaster(app Application)
  27. RegisterShutdownHook(hook ShutdownHook)
  28. Listen() error
  29. Stop()
  30. Config() *config.Config
  31. Dependencies() *mappers.DependencyMapper
  32. Logger() *logging.Log
  33. Router() *Router
  34. Extensions() *ExtensionManager
  35. Reload(config *config.Config)
  36. }
  37. type Controller interface {
  38. middleware() Middleware
  39. name() string
  40. mandatoryNoSlash() bool
  41. mandatorySlash() bool
  42. optionalSlash() bool
  43. slashIsDefault() bool
  44. noInterpolation() bool
  45. path() string
  46. prefix() string
  47. index() string
  48. webSocketPath() string
  49. upgrader() *websocket.Upgrader
  50. renderer() render.Renderer
  51. endpoints() map[string]RouteFlag
  52. options() BaseController
  53. }
  54. type ConnectHandler interface {
  55. Connect(Context) error
  56. }
  57. type DeleteHandler interface {
  58. Delete(Context) error
  59. }
  60. type GetHandler interface {
  61. Get(Context) error
  62. }
  63. type HeadHandler interface {
  64. Head(Context) error
  65. }
  66. type OptionsHandler interface {
  67. Options(Context) error
  68. }
  69. type PostHandler interface {
  70. Post(Context) error
  71. }
  72. type PutHandler interface {
  73. Put(Context) error
  74. }
  75. type PatchHandler interface {
  76. Patch(Context) error
  77. }
  78. type TraceHandler interface {
  79. Trace(Context) error
  80. }
  81. // Binder controllers are those that wish to implement or handle binding
  82. // themselves. Consequently, a *Router is passed as the Bind() function's sole
  83. // argument such that the controller may use it to interface directly with the
  84. // router instance or may call Router.Mux() to use the muxer directly. If an
  85. // implementation uses the latter, the underlying configured go-chi instance is
  86. // exposed for external management.
  87. type Binder interface {
  88. Bind(*Router)
  89. }
  90. type IndexHandler interface {
  91. Index(Context) error
  92. }
  93. // MiddlewareHandler, when implemented, allows controllers to return middleware
  94. // that utilizes attached fields and methods as internal context. This is useful
  95. // if your middleware requires access to a database or other dependencies
  96. // (including injected dependencies).
  97. type MiddlewareHandler interface {
  98. Middleware() []func(http.Handler) http.Handler
  99. }
  100. type WebSocketHandler interface {
  101. WebSocket(Context) error
  102. }
  103. // MapperHandler returns a map of a route (map key) and the endpoint + method
  104. // (RouteMap) it should be bound to. MapperHandlers are controllers that define
  105. // their own route-to-endpoint handling routines.
  106. type MapperHandler interface {
  107. Mapper() map[string]RouteMap
  108. }
  109. type BaseController struct {
  110. route *Route
  111. // Middleware defined for this controller.
  112. Middleware Middleware
  113. // Name to assign to this controller. Leave empty to automatically deduce
  114. // the name from the implementing struct.
  115. Name string
  116. // Path against which this controller will bind its routes. This may have
  117. // special meaning for index and other methods (e.g. custom).
  118. Path string
  119. // Paths to additionally assign to this controller and its methods. Not
  120. // currently used.
  121. Paths map[string][]string
  122. // Prefix to prepend to the controller's symbolic name. This may be useful
  123. // for namespacing controller references for reversing the URL in templates.
  124. Prefix string
  125. // OptionalSlash indicates the trailing slash is optional. It is usually
  126. // advised to set this via the Path component.
  127. OptionalSlash bool
  128. // Endpoints is a list of custom endpoints attached to this controller.
  129. Endpoints map[string]RouteFlag
  130. // MandatoryNoSlash indicates the trailing slash must not be present. It is
  131. // usually advised to set this via the Path component.
  132. MandatoryNoSlash bool
  133. // MandatorySlash indicates the trailing slash is required. It is usually
  134. // advised to set this via the Path component.
  135. MandatorySlash bool
  136. // SlashIsDefault indicates the presence or absence of the trailing slash is
  137. // the default state. This flag only holds meaning when OptionalSlash is set
  138. // to true. It is usually advised to set this via the Path component by
  139. // including a slash followed by a question mark ("/?") to indicate that the
  140. // slash is optional and the default redirection target.
  141. SlashIsDefault bool
  142. // NoInterpolation disables path interpolation and mandates the flags
  143. // (above) to configure the route slash states. This is useful for routes
  144. // where the special characters used to communicate slash behavior are
  145. // required as part of the route and should be accepted as literals.
  146. NoInterpolation bool
  147. // WebSocketPath, if set, will attach the WebSocket() method to the
  148. // specified path underneath the path defined for this controller.
  149. // Recommended.
  150. //
  151. // Leave this blank if your controller is intended strictly for websocket
  152. // handling.
  153. WebSocketPath string
  154. // Upgrader is the configured websocket upgrader via gorilla/websocket. This
  155. // provides both the configuration details for websocket connections in
  156. // addition to bound methods for upgrading the connection. If this is nil
  157. // and the controller implements the WebSocketHandler interface, the default
  158. // upgrader will be used instead.
  159. Upgrader *websocket.Upgrader
  160. // Renderer reference for this controller. This may be unique to each
  161. // controller or may be set globally via a helper.
  162. Renderer render.Renderer
  163. // BeforeResponse bindings specifically used for this controller.
  164. BeforeResponse []func(Context, *Route) error
  165. // AfterResponse bindings specifically used for this controller.
  166. AfterResponse []func(Context, error) error
  167. // Index path override. This may contain a path component, a single slash
  168. // indicating the path terminates with this index, a slash followed by a
  169. // question mark which indicates the slash is optional, or a slash followed
  170. // by an exclamation point indicating the route must not terminate with a
  171. // slash.
  172. Index string
  173. // Method path overrides.
  174. // Get overrides the default path for GET requests, appending the path
  175. // component specified here.
  176. Get string
  177. // Post overrides the default path for POST requests, appending the path
  178. // component specified here.
  179. Post string
  180. // Put overrides the default path for PUT requests, appending the path
  181. // component specified here.
  182. Put string
  183. // Patch overrides the default path for PATCH requests, appending the path
  184. // component specified here.
  185. Patch string
  186. // Delete overrides the default path for DELETE requests, appending the path
  187. // component specified here.
  188. Delete string
  189. // Head overrides the default path for HEAD requests, appending the path
  190. // component specified here.
  191. Head string
  192. }
  193. func (bc BaseController) middleware() Middleware {
  194. return bc.Middleware
  195. }
  196. func (bc BaseController) name() string {
  197. return bc.Name
  198. }
  199. func (bc BaseController) mandatoryNoSlash() bool {
  200. return bc.MandatoryNoSlash
  201. }
  202. func (bc BaseController) mandatorySlash() bool {
  203. return bc.MandatorySlash
  204. }
  205. func (bc BaseController) optionalSlash() bool {
  206. return bc.OptionalSlash
  207. }
  208. func (bc BaseController) slashIsDefault() bool {
  209. return bc.SlashIsDefault
  210. }
  211. func (bc BaseController) noInterpolation() bool {
  212. return bc.NoInterpolation
  213. }
  214. func (bc BaseController) path() string {
  215. return bc.Path
  216. }
  217. func (bc BaseController) prefix() string {
  218. return bc.Prefix
  219. }
  220. func (bc BaseController) renderer() render.Renderer {
  221. return bc.Renderer
  222. }
  223. func (bc BaseController) beforeResponseHandlers() []func(Context, *Route) error {
  224. return bc.BeforeResponse
  225. }
  226. func (bc BaseController) afterResponseHandlers() []func(Context, error) error {
  227. return bc.AfterResponse
  228. }
  229. func (bc BaseController) webSocketPath() string {
  230. return bc.WebSocketPath
  231. }
  232. func (bc BaseController) upgrader() *websocket.Upgrader {
  233. return bc.Upgrader
  234. }
  235. func (bc BaseController) index() string {
  236. return bc.Index
  237. }
  238. func (bc BaseController) endpoints() map[string]RouteFlag {
  239. return bc.Endpoints
  240. }
  241. func (bc BaseController) options() BaseController {
  242. return bc
  243. }
  244. type Context interface {
  245. Float(string) (float64, error)
  246. FloatDefault(string, float64) float64
  247. Int(string) (int64, error)
  248. IntDefault(string, int64) int64
  249. Param(string) string
  250. ParamDefault(string, string) string
  251. Params(string) []string
  252. String(string) (string, error)
  253. StringDefault(string, string) string
  254. In(interface{}) error
  255. JSON(interface{}) error
  256. ParamTypes() map[string]string
  257. Render(string, interface{}) error
  258. Renderer() (render.ContextRenderer, error)
  259. SetRenderer(render.Renderer)
  260. Headers() http.Header
  261. Request() *http.Request
  262. Response() http.ResponseWriter
  263. RequestContext(key string, value interface{})
  264. Route() *Route
  265. SetCookie(*http.Cookie)
  266. WebSocket() *websocket.Conn
  267. SetWebSocket(*websocket.Conn)
  268. Session() session.Session
  269. URLFor(string) *URLBuilder
  270. Write([]byte) (int, error)
  271. WriteHeader(int)
  272. WriteJSON(interface{}) error
  273. ContentType(ContentType)
  274. HasError() error
  275. Panic(string)
  276. Error() string
  277. SetError(error)
  278. Code() int
  279. SetCode(int)
  280. }