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.

937 lines
31KB

  1. package iris
  2. import (
  3. stdContext "context"
  4. "errors"
  5. "fmt"
  6. "io"
  7. "log"
  8. "net"
  9. "net/http"
  10. "os"
  11. "regexp"
  12. "strings"
  13. "sync"
  14. "time"
  15. "github.com/kataras/iris/v12/context"
  16. "github.com/kataras/iris/v12/core/host"
  17. "github.com/kataras/iris/v12/core/netutil"
  18. "github.com/kataras/iris/v12/core/router"
  19. "github.com/kataras/iris/v12/i18n"
  20. "github.com/kataras/iris/v12/middleware/accesslog"
  21. "github.com/kataras/iris/v12/middleware/recover"
  22. "github.com/kataras/iris/v12/middleware/requestid"
  23. "github.com/kataras/iris/v12/view"
  24. "github.com/kataras/golog"
  25. "github.com/kataras/tunnel"
  26. "github.com/tdewolff/minify/v2"
  27. "github.com/tdewolff/minify/v2/css"
  28. "github.com/tdewolff/minify/v2/html"
  29. "github.com/tdewolff/minify/v2/js"
  30. "github.com/tdewolff/minify/v2/json"
  31. "github.com/tdewolff/minify/v2/svg"
  32. "github.com/tdewolff/minify/v2/xml"
  33. )
  34. // Version is the current version of the Iris Web Framework.
  35. const Version = "12.2.0-alpha"
  36. // Byte unit helpers.
  37. const (
  38. B = 1 << (10 * iota)
  39. KB
  40. MB
  41. GB
  42. TB
  43. PB
  44. EB
  45. )
  46. // Application is responsible to manage the state of the application.
  47. // It contains and handles all the necessary parts to create a fast web server.
  48. type Application struct {
  49. // routing embedded | exposing APIBuilder's and Router's public API.
  50. *router.APIBuilder
  51. *router.Router
  52. router.HTTPErrorHandler // if Router is Downgraded this is nil.
  53. ContextPool *context.Pool
  54. // config contains the configuration fields
  55. // all fields defaults to something that is working, developers don't have to set it.
  56. config *Configuration
  57. // the golog logger instance, defaults to "Info" level messages (all except "Debug")
  58. logger *golog.Logger
  59. // I18n contains localization and internationalization support.
  60. // Use the `Load` or `LoadAssets` to locale language files.
  61. //
  62. // See `Context#Tr` method for request-based translations.
  63. I18n *i18n.I18n
  64. // Validator is the request body validator, defaults to nil.
  65. Validator context.Validator
  66. // Minifier to minify responses.
  67. minifier *minify.M
  68. // view engine
  69. view view.View
  70. // used for build
  71. builded bool
  72. defaultMode bool
  73. // OnBuild is a single function which
  74. // is fired on the first `Build` method call.
  75. // If reports an error then the execution
  76. // is stopped and the error is logged.
  77. // It's nil by default except when `Switch` instead of `New` or `Default`
  78. // is used to initialize the Application.
  79. // Users can wrap it to accept more events.
  80. OnBuild func() error
  81. mu sync.Mutex
  82. // name is the application name and the log prefix for
  83. // that Application instance's Logger. See `SetName` and `String`.
  84. // Defaults to IRIS_APP_NAME envrinoment variable otherwise empty.
  85. name string
  86. // Hosts contains a list of all servers (Host Supervisors) that this app is running on.
  87. //
  88. // Hosts may be empty only if application ran(`app.Run`) with `iris.Raw` option runner,
  89. // otherwise it contains a single host (`app.Hosts[0]`).
  90. //
  91. // Additional Host Supervisors can be added to that list by calling the `app.NewHost` manually.
  92. //
  93. // Hosts field is available after `Run` or `NewHost`.
  94. Hosts []*host.Supervisor
  95. hostConfigurators []host.Configurator
  96. }
  97. // New creates and returns a fresh empty iris *Application instance.
  98. func New() *Application {
  99. config := DefaultConfiguration()
  100. app := &Application{
  101. config: &config,
  102. Router: router.NewRouter(),
  103. I18n: i18n.New(),
  104. minifier: newMinifier(),
  105. }
  106. logger := newLogger(app)
  107. app.logger = logger
  108. app.APIBuilder = router.NewAPIBuilder(logger)
  109. app.ContextPool = context.New(func() interface{} {
  110. return context.NewContext(app)
  111. })
  112. context.RegisterApplication(app)
  113. return app
  114. }
  115. // Default returns a new Application.
  116. // Default with "debug" Logger Level.
  117. // Localization enabled on "./locales" directory
  118. // and HTML templates on "./views" or "./templates" directory.
  119. // It runs with the AccessLog on "./access.log",
  120. // Recovery and Request ID middleware already attached.
  121. func Default() *Application {
  122. app := New()
  123. // Set default log level.
  124. app.logger.SetLevel("debug")
  125. app.logger.Debugf(`Log level set to "debug"`)
  126. // Register the accesslog middleware.
  127. logFile, err := os.OpenFile("./access.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0600)
  128. if err == nil {
  129. // Close the file on shutdown.
  130. app.ConfigureHost(func(su *Supervisor) {
  131. su.RegisterOnShutdown(func() {
  132. logFile.Close()
  133. })
  134. })
  135. ac := accesslog.New(logFile)
  136. ac.AddOutput(app.logger.Printer)
  137. app.UseRouter(ac.Handler)
  138. app.logger.Debugf("Using <%s> to log requests", logFile.Name())
  139. }
  140. // Register the requestid middleware
  141. // before recover so current Context.GetID() contains the info on panic logs.
  142. app.UseRouter(requestid.New())
  143. app.logger.Debugf("Using <UUID4> to identify requests")
  144. // Register the recovery, after accesslog and recover,
  145. // before end-developer's middleware.
  146. app.UseRouter(recover.New())
  147. app.defaultMode = true
  148. return app
  149. }
  150. func newLogger(app *Application) *golog.Logger {
  151. logger := golog.Default.Child(app)
  152. if name := os.Getenv("IRIS_APP_NAME"); name != "" {
  153. app.name = name
  154. logger.SetChildPrefix(name)
  155. }
  156. return logger
  157. }
  158. // SetName sets a unique name to this Iris Application.
  159. // It sets a child prefix for the current Application's Logger.
  160. // Look `String` method too.
  161. //
  162. // It returns this Application.
  163. func (app *Application) SetName(appName string) *Application {
  164. app.mu.Lock()
  165. defer app.mu.Unlock()
  166. if app.name == "" {
  167. app.logger.SetChildPrefix(appName)
  168. }
  169. app.name = appName
  170. return app
  171. }
  172. // String completes the fmt.Stringer interface and it returns
  173. // the application's name.
  174. // If name was not set by `SetName` or `IRIS_APP_NAME` environment variable
  175. // then this will return an empty string.
  176. func (app *Application) String() string {
  177. return app.name
  178. }
  179. // WWW creates and returns a "www." subdomain.
  180. // The difference from `app.Subdomain("www")` or `app.Party("www.")` is that the `app.WWW()` method
  181. // wraps the router so all http(s)://mydomain.com will be redirect to http(s)://www.mydomain.com.
  182. // Other subdomains can be registered using the app: `sub := app.Subdomain("mysubdomain")`,
  183. // child subdomains can be registered using the www := app.WWW(); www.Subdomain("wwwchildSubdomain").
  184. func (app *Application) WWW() router.Party {
  185. return app.SubdomainRedirect(app, app.Subdomain("www"))
  186. }
  187. // SubdomainRedirect registers a router wrapper which
  188. // redirects(StatusMovedPermanently) a (sub)domain to another subdomain or to the root domain as fast as possible,
  189. // before the router's try to execute route's handler(s).
  190. //
  191. // It receives two arguments, they are the from and to/target locations,
  192. // 'from' can be a wildcard subdomain as well (app.WildcardSubdomain())
  193. // 'to' is not allowed to be a wildcard for obvious reasons,
  194. // 'from' can be the root domain(app) when the 'to' is not the root domain and visa-versa.
  195. //
  196. // Usage:
  197. // www := app.Subdomain("www") <- same as app.Party("www.")
  198. // app.SubdomainRedirect(app, www)
  199. // This will redirect all http(s)://mydomain.com/%anypath% to http(s)://www.mydomain.com/%anypath%.
  200. //
  201. // One or more subdomain redirects can be used to the same app instance.
  202. //
  203. // If you need more information about this implementation then you have to navigate through
  204. // the `core/router#NewSubdomainRedirectWrapper` function instead.
  205. //
  206. // Example: https://github.com/kataras/iris/tree/master/_examples/routing/subdomains/redirect
  207. func (app *Application) SubdomainRedirect(from, to router.Party) router.Party {
  208. sd := router.NewSubdomainRedirectWrapper(app.ConfigurationReadOnly().GetVHost, from.GetRelPath(), to.GetRelPath())
  209. app.Router.AddRouterWrapper(sd)
  210. return to
  211. }
  212. // Configure can called when modifications to the framework instance needed.
  213. // It accepts the framework instance
  214. // and returns an error which if it's not nil it's printed to the logger.
  215. // See configuration.go for more.
  216. //
  217. // Returns itself in order to be used like `app:= New().Configure(...)`
  218. func (app *Application) Configure(configurators ...Configurator) *Application {
  219. for _, cfg := range configurators {
  220. if cfg != nil {
  221. cfg(app)
  222. }
  223. }
  224. return app
  225. }
  226. // ConfigurationReadOnly returns an object which doesn't allow field writing.
  227. func (app *Application) ConfigurationReadOnly() context.ConfigurationReadOnly {
  228. return app.config
  229. }
  230. // Logger returns the golog logger instance(pointer) that is being used inside the "app".
  231. //
  232. // Available levels:
  233. // - "disable"
  234. // - "fatal"
  235. // - "error"
  236. // - "warn"
  237. // - "info"
  238. // - "debug"
  239. // Usage: app.Logger().SetLevel("error")
  240. // Or set the level through Configurartion's LogLevel or WithLogLevel functional option.
  241. // Defaults to "info" level.
  242. //
  243. // Callers can use the application's logger which is
  244. // the same `golog.Default.LastChild()` logger,
  245. // to print custom logs too.
  246. // Usage:
  247. // app.Logger().Error/Errorf("...")
  248. // app.Logger().Warn/Warnf("...")
  249. // app.Logger().Info/Infof("...")
  250. // app.Logger().Debug/Debugf("...")
  251. //
  252. // Setting one or more outputs: app.Logger().SetOutput(io.Writer...)
  253. // Adding one or more outputs : app.Logger().AddOutput(io.Writer...)
  254. //
  255. // Adding custom levels requires import of the `github.com/kataras/golog` package:
  256. // First we create our level to a golog.Level
  257. // in order to be used in the Log functions.
  258. // var SuccessLevel golog.Level = 6
  259. // Register our level, just three fields.
  260. // golog.Levels[SuccessLevel] = &golog.LevelMetadata{
  261. // Name: "success",
  262. // RawText: "[SUCC]",
  263. // // ColorfulText (Green Color[SUCC])
  264. // ColorfulText: "\x1b[32m[SUCC]\x1b[0m",
  265. // }
  266. // Usage:
  267. // app.Logger().SetLevel("success")
  268. // app.Logger().Logf(SuccessLevel, "a custom leveled log message")
  269. func (app *Application) Logger() *golog.Logger {
  270. return app.logger
  271. }
  272. // IsDebug reports whether the application is running
  273. // under debug/development mode.
  274. // It's just a shortcut of Logger().Level >= golog.DebugLevel.
  275. // The same method existss as Context.IsDebug() too.
  276. func (app *Application) IsDebug() bool {
  277. return app.logger.Level >= golog.DebugLevel
  278. }
  279. // I18nReadOnly returns the i18n's read-only features.
  280. // See `I18n` method for more.
  281. func (app *Application) I18nReadOnly() context.I18nReadOnly {
  282. return app.I18n
  283. }
  284. // Validate validates a value and returns nil if passed or
  285. // the failure reason if does not.
  286. func (app *Application) Validate(v interface{}) error {
  287. if app.Validator == nil {
  288. return nil
  289. }
  290. // val := reflect.ValueOf(v)
  291. // if val.Kind() == reflect.Ptr && !val.IsNil() {
  292. // val = val.Elem()
  293. // }
  294. // if val.Kind() == reflect.Struct && val.Type() != timeType {
  295. // return app.Validator.Struct(v)
  296. // }
  297. // no need to check the kind, underline lib does it but in the future this may change (look above).
  298. err := app.Validator.Struct(v)
  299. if err != nil {
  300. if !strings.HasPrefix(err.Error(), "validator: ") {
  301. return err
  302. }
  303. }
  304. return nil
  305. }
  306. func newMinifier() *minify.M {
  307. m := minify.New()
  308. m.AddFunc("text/css", css.Minify)
  309. m.AddFunc("text/html", html.Minify)
  310. m.AddFunc("image/svg+xml", svg.Minify)
  311. m.AddFuncRegexp(regexp.MustCompile("^(application|text)/(x-)?(java|ecma)script$"), js.Minify)
  312. m.AddFuncRegexp(regexp.MustCompile("[/+]json$"), json.Minify)
  313. m.AddFuncRegexp(regexp.MustCompile("[/+]xml$"), xml.Minify)
  314. return m
  315. }
  316. // Minify is a middleware which minifies the responses
  317. // based on the response content type.
  318. // Note that minification might be slower, caching is advised.
  319. // Customize the minifier through `Application.Minifier()`.
  320. // Usage:
  321. // app.Use(iris.Minify)
  322. func Minify(ctx Context) {
  323. w := ctx.Application().Minifier().ResponseWriter(ctx.ResponseWriter().Naive(), ctx.Request())
  324. // Note(@kataras):
  325. // We don't use defer w.Close()
  326. // because this response writer holds a sync.WaitGroup under the hoods
  327. // and we MUST be sure that its wg.Wait is called on request cancelation
  328. // and not in the end of handlers chain execution
  329. // (which if running a time-consuming task it will delay its resource release).
  330. ctx.OnCloseErr(w.Close)
  331. ctx.ResponseWriter().SetWriter(w)
  332. ctx.Next()
  333. }
  334. // Minifier returns the minifier instance.
  335. // By default it can minifies:
  336. // - text/html
  337. // - text/css
  338. // - image/svg+xml
  339. // - application/text(javascript, ecmascript, json, xml).
  340. // Use that instance to add custom Minifiers before server ran.
  341. func (app *Application) Minifier() *minify.M {
  342. return app.minifier
  343. }
  344. // RegisterView registers a view engine for the application.
  345. // Children can register their own too. If no Party view Engine is registered
  346. // then this one will be used to render the templates instead.
  347. func (app *Application) RegisterView(viewEngine view.Engine) {
  348. app.view.Register(viewEngine)
  349. }
  350. // View executes and writes the result of a template file to the writer.
  351. //
  352. // First parameter is the writer to write the parsed template.
  353. // Second parameter is the relative, to templates directory, template filename, including extension.
  354. // Third parameter is the layout, can be empty string.
  355. // Forth parameter is the bindable data to the template, can be nil.
  356. //
  357. // Use context.View to render templates to the client instead.
  358. // Returns an error on failure, otherwise nil.
  359. func (app *Application) View(writer io.Writer, filename string, layout string, bindingData interface{}) error {
  360. if !app.view.Registered() {
  361. err := errors.New("view engine is missing, use `RegisterView`")
  362. app.logger.Error(err)
  363. return err
  364. }
  365. return app.view.ExecuteWriter(writer, filename, layout, bindingData)
  366. }
  367. // ConfigureHost accepts one or more `host#Configuration`, these configurators functions
  368. // can access the host created by `app.Run` or `app.Listen`,
  369. // they're being executed when application is ready to being served to the public.
  370. //
  371. // It's an alternative way to interact with a host that is automatically created by
  372. // `app.Run`.
  373. //
  374. // These "configurators" can work side-by-side with the `iris#Addr, iris#Server, iris#TLS, iris#AutoTLS, iris#Listener`
  375. // final arguments("hostConfigs") too.
  376. //
  377. // Note that these application's host "configurators" will be shared with the rest of
  378. // the hosts that this app will may create (using `app.NewHost`), meaning that
  379. // `app.NewHost` will execute these "configurators" everytime that is being called as well.
  380. //
  381. // These "configurators" should be registered before the `app.Run` or `host.Serve/Listen` functions.
  382. func (app *Application) ConfigureHost(configurators ...host.Configurator) *Application {
  383. app.mu.Lock()
  384. app.hostConfigurators = append(app.hostConfigurators, configurators...)
  385. app.mu.Unlock()
  386. return app
  387. }
  388. // NewHost accepts a standard *http.Server object,
  389. // completes the necessary missing parts of that "srv"
  390. // and returns a new, ready-to-use, host (supervisor).
  391. func (app *Application) NewHost(srv *http.Server) *host.Supervisor {
  392. app.mu.Lock()
  393. defer app.mu.Unlock()
  394. // set the server's handler to the framework's router
  395. if srv.Handler == nil {
  396. srv.Handler = app.Router
  397. }
  398. // check if different ErrorLog provided, if not bind it with the framework's logger
  399. if srv.ErrorLog == nil {
  400. srv.ErrorLog = log.New(app.logger.Printer.Output, "[HTTP Server] ", 0)
  401. }
  402. if addr := srv.Addr; addr == "" {
  403. addr = ":8080"
  404. if len(app.Hosts) > 0 {
  405. if v := app.Hosts[0].Server.Addr; v != "" {
  406. addr = v
  407. }
  408. }
  409. srv.Addr = addr
  410. }
  411. // app.logger.Debugf("Host: addr is %s", srv.Addr)
  412. // create the new host supervisor
  413. // bind the constructed server and return it
  414. su := host.New(srv)
  415. if app.config.vhost == "" { // vhost now is useful for router subdomain on wildcard subdomains,
  416. // in order to correct decide what to do on:
  417. // mydomain.com -> invalid
  418. // localhost -> invalid
  419. // sub.mydomain.com -> valid
  420. // sub.localhost -> valid
  421. // we need the host (without port if 80 or 443) in order to validate these, so:
  422. app.config.vhost = netutil.ResolveVHost(srv.Addr)
  423. }
  424. // app.logger.Debugf("Host: virtual host is %s", app.config.vhost)
  425. // the below schedules some tasks that will run among the server
  426. if !app.config.DisableStartupLog {
  427. // show the available info to exit from app.
  428. su.RegisterOnServe(host.WriteStartupLogOnServe(app.logger.Printer.Output)) // app.logger.Writer -> Info
  429. // app.logger.Debugf("Host: register startup notifier")
  430. }
  431. if !app.config.DisableInterruptHandler {
  432. // when CTRL/CMD+C pressed.
  433. shutdownTimeout := 10 * time.Second
  434. host.RegisterOnInterrupt(host.ShutdownOnInterrupt(su, shutdownTimeout))
  435. // app.logger.Debugf("Host: register server shutdown on interrupt(CTRL+C/CMD+C)")
  436. }
  437. su.IgnoredErrors = append(su.IgnoredErrors, app.config.IgnoreServerErrors...)
  438. if len(su.IgnoredErrors) > 0 {
  439. app.logger.Debugf("Host: server will ignore the following errors: %s", su.IgnoredErrors)
  440. }
  441. su.Configure(app.hostConfigurators...)
  442. app.Hosts = append(app.Hosts, su)
  443. return su
  444. }
  445. // Shutdown gracefully terminates all the application's server hosts and any tunnels.
  446. // Returns an error on the first failure, otherwise nil.
  447. func (app *Application) Shutdown(ctx stdContext.Context) error {
  448. app.mu.Lock()
  449. defer app.mu.Unlock()
  450. for i, su := range app.Hosts {
  451. app.logger.Debugf("Host[%d]: Shutdown now", i)
  452. if err := su.Shutdown(ctx); err != nil {
  453. app.logger.Debugf("Host[%d]: Error while trying to shutdown", i)
  454. return err
  455. }
  456. }
  457. for _, t := range app.config.Tunneling.Tunnels {
  458. if t.Name == "" {
  459. continue
  460. }
  461. if err := app.config.Tunneling.StopTunnel(t); err != nil {
  462. return err
  463. }
  464. }
  465. return nil
  466. }
  467. // Build sets up, once, the framework.
  468. // It builds the default router with its default macros
  469. // and the template functions that are very-closed to iris.
  470. //
  471. // If error occurred while building the Application, the returns type of error will be an *errgroup.Group
  472. // which let the callers to inspect the errors and cause, usage:
  473. //
  474. // import "github.com/kataras/iris/v12/core/errgroup"
  475. //
  476. // errgroup.Walk(app.Build(), func(typ interface{}, err error) {
  477. // app.Logger().Errorf("%s: %s", typ, err)
  478. // })
  479. func (app *Application) Build() error {
  480. if app.builded {
  481. return nil
  482. }
  483. if cb := app.OnBuild; cb != nil {
  484. if err := cb(); err != nil {
  485. return err
  486. }
  487. }
  488. // start := time.Now()
  489. app.builded = true // even if fails.
  490. // check if a prior app.Logger().SetLevel called and if not
  491. // then set the defined configuration's log level.
  492. if app.logger.Level == golog.InfoLevel /* the default level */ {
  493. app.logger.SetLevel(app.config.LogLevel)
  494. }
  495. if app.defaultMode { // the app.I18n and app.View will be not available until Build.
  496. if !app.I18n.Loaded() {
  497. for _, s := range []string{"./locales/*/*", "./locales/*", "./translations"} {
  498. if _, err := os.Stat(s); err != nil {
  499. continue
  500. }
  501. if err := app.I18n.Load(s); err != nil {
  502. continue
  503. }
  504. app.I18n.SetDefault("en-US")
  505. break
  506. }
  507. }
  508. if !app.view.Registered() {
  509. for _, s := range []string{"./views", "./templates", "./web/views"} {
  510. if _, err := os.Stat(s); err != nil {
  511. continue
  512. }
  513. app.RegisterView(HTML(s, ".html"))
  514. break
  515. }
  516. }
  517. }
  518. if app.I18n.Loaded() {
  519. // {{ tr "lang" "key" arg1 arg2 }}
  520. app.view.AddFunc("tr", app.I18n.Tr)
  521. app.Router.PrependRouterWrapper(app.I18n.Wrapper())
  522. }
  523. if app.view.Registered() {
  524. app.logger.Debugf("Application: view engine %q is registered", app.view.Name())
  525. // view engine
  526. // here is where we declare the closed-relative framework functions.
  527. // Each engine has their defaults, i.e yield,render,render_r,partial, params...
  528. rv := router.NewRoutePathReverser(app.APIBuilder)
  529. app.view.AddFunc("urlpath", rv.Path)
  530. // app.view.AddFunc("url", rv.URL)
  531. if err := app.view.Load(); err != nil {
  532. app.logger.Errorf("View Builder: %v", err)
  533. return err
  534. }
  535. }
  536. if !app.Router.Downgraded() {
  537. // router
  538. if _, err := injectLiveReload(app); err != nil {
  539. app.logger.Errorf("LiveReload: init: failed: %v", err)
  540. return err
  541. }
  542. if app.config.ForceLowercaseRouting {
  543. // This should always be executed first.
  544. app.Router.PrependRouterWrapper(func(w http.ResponseWriter, r *http.Request, next http.HandlerFunc) {
  545. r.Host = strings.ToLower(r.Host)
  546. r.URL.Host = strings.ToLower(r.URL.Host)
  547. r.URL.Path = strings.ToLower(r.URL.Path)
  548. next(w, r)
  549. })
  550. }
  551. // create the request handler, the default routing handler
  552. routerHandler := router.NewDefaultHandler(app.config, app.logger)
  553. err := app.Router.BuildRouter(app.ContextPool, routerHandler, app.APIBuilder, false)
  554. if err != nil {
  555. app.logger.Error(err)
  556. return err
  557. }
  558. app.HTTPErrorHandler = routerHandler
  559. // re-build of the router from outside can be done with
  560. // app.RefreshRouter()
  561. }
  562. // if end := time.Since(start); end.Seconds() > 5 {
  563. // app.logger.Debugf("Application: build took %s", time.Since(start))
  564. return nil
  565. }
  566. // Runner is just an interface which accepts the framework instance
  567. // and returns an error.
  568. //
  569. // It can be used to register a custom runner with `Run` in order
  570. // to set the framework's server listen action.
  571. //
  572. // Currently `Runner` is being used to declare the builtin server listeners.
  573. //
  574. // See `Run` for more.
  575. type Runner func(*Application) error
  576. // Listener can be used as an argument for the `Run` method.
  577. // It can start a server with a custom net.Listener via server's `Serve`.
  578. //
  579. // Second argument is optional, it accepts one or more
  580. // `func(*host.Configurator)` that are being executed
  581. // on that specific host that this function will create to start the server.
  582. // Via host configurators you can configure the back-end host supervisor,
  583. // i.e to add events for shutdown, serve or error.
  584. // An example of this use case can be found at:
  585. // https://github.com/kataras/iris/blob/master/_examples/http-server/notify-on-shutdown/main.go
  586. // Look at the `ConfigureHost` too.
  587. //
  588. // See `Run` for more.
  589. func Listener(l net.Listener, hostConfigs ...host.Configurator) Runner {
  590. return func(app *Application) error {
  591. app.config.vhost = netutil.ResolveVHost(l.Addr().String())
  592. return app.NewHost(&http.Server{Addr: l.Addr().String()}).
  593. Configure(hostConfigs...).
  594. Serve(l)
  595. }
  596. }
  597. // Server can be used as an argument for the `Run` method.
  598. // It can start a server with a *http.Server.
  599. //
  600. // Second argument is optional, it accepts one or more
  601. // `func(*host.Configurator)` that are being executed
  602. // on that specific host that this function will create to start the server.
  603. // Via host configurators you can configure the back-end host supervisor,
  604. // i.e to add events for shutdown, serve or error.
  605. // An example of this use case can be found at:
  606. // https://github.com/kataras/iris/blob/master/_examples/http-server/notify-on-shutdown/main.go
  607. // Look at the `ConfigureHost` too.
  608. //
  609. // See `Run` for more.
  610. func Server(srv *http.Server, hostConfigs ...host.Configurator) Runner {
  611. return func(app *Application) error {
  612. return app.NewHost(srv).
  613. Configure(hostConfigs...).
  614. ListenAndServe()
  615. }
  616. }
  617. // Addr can be used as an argument for the `Run` method.
  618. // It accepts a host address which is used to build a server
  619. // and a listener which listens on that host and port.
  620. //
  621. // Addr should have the form of [host]:port, i.e localhost:8080 or :8080.
  622. //
  623. // Second argument is optional, it accepts one or more
  624. // `func(*host.Configurator)` that are being executed
  625. // on that specific host that this function will create to start the server.
  626. // Via host configurators you can configure the back-end host supervisor,
  627. // i.e to add events for shutdown, serve or error.
  628. // An example of this use case can be found at:
  629. // https://github.com/kataras/iris/blob/master/_examples/http-server/notify-on-shutdown/main.go
  630. // Look at the `ConfigureHost` too.
  631. //
  632. // See `Run` for more.
  633. func Addr(addr string, hostConfigs ...host.Configurator) Runner {
  634. return func(app *Application) error {
  635. return app.NewHost(&http.Server{Addr: addr}).
  636. Configure(hostConfigs...).
  637. ListenAndServe()
  638. }
  639. }
  640. var (
  641. // TLSNoRedirect is a `host.Configurator` which can be passed as last argument
  642. // to the `TLS` runner function. It disables the automatic
  643. // registration of redirection from "http://" to "https://" requests.
  644. // Applies only to the `TLS` runner.
  645. // See `AutoTLSNoRedirect` to register a custom fallback server for `AutoTLS` runner.
  646. TLSNoRedirect = func(su *host.Supervisor) { su.NoRedirect() }
  647. // AutoTLSNoRedirect is a `host.Configurator`.
  648. // It registers a fallback HTTP/1.1 server for the `AutoTLS` one.
  649. // The function accepts the letsencrypt wrapper and it
  650. // should return a valid instance of http.Server which its handler should be the result
  651. // of the "acmeHandler" wrapper.
  652. // Usage:
  653. // getServer := func(acme func(http.Handler) http.Handler) *http.Server {
  654. // srv := &http.Server{Handler: acme(yourCustomHandler), ...otherOptions}
  655. // go srv.ListenAndServe()
  656. // return srv
  657. // }
  658. // app.Run(iris.AutoTLS(":443", "example.com example2.com", "mail@example.com", getServer))
  659. //
  660. // Note that if Server.Handler is nil then the server is automatically ran
  661. // by the framework and the handler set to automatic redirection, it's still
  662. // a valid option when the caller wants just to customize the server's fields (except Addr).
  663. // With this host configurator the caller can customize the server
  664. // that letsencrypt relies to perform the challenge.
  665. // LetsEncrypt Certification Manager relies on http://example.com/.well-known/acme-challenge/<TOKEN>.
  666. AutoTLSNoRedirect = func(getFallbackServer func(acmeHandler func(fallback http.Handler) http.Handler) *http.Server) host.Configurator {
  667. return func(su *host.Supervisor) {
  668. su.NoRedirect()
  669. su.Fallback = getFallbackServer
  670. }
  671. }
  672. )
  673. // TLS can be used as an argument for the `Run` method.
  674. // It will start the Application's secure server.
  675. //
  676. // Use it like you used to use the http.ListenAndServeTLS function.
  677. //
  678. // Addr should have the form of [host]:port, i.e localhost:443 or :443.
  679. // "certFileOrContents" & "keyFileOrContents" should be filenames with their extensions
  680. // or raw contents of the certificate and the private key.
  681. //
  682. // Last argument is optional, it accepts one or more
  683. // `func(*host.Configurator)` that are being executed
  684. // on that specific host that this function will create to start the server.
  685. // Via host configurators you can configure the back-end host supervisor,
  686. // i.e to add events for shutdown, serve or error.
  687. // An example of this use case can be found at:
  688. // https://github.com/kataras/iris/blob/master/_examples/http-server/notify-on-shutdown/main.go
  689. // Look at the `ConfigureHost` too.
  690. //
  691. // See `Run` for more.
  692. func TLS(addr string, certFileOrContents, keyFileOrContents string, hostConfigs ...host.Configurator) Runner {
  693. return func(app *Application) error {
  694. return app.NewHost(&http.Server{Addr: addr}).
  695. Configure(hostConfigs...).
  696. ListenAndServeTLS(certFileOrContents, keyFileOrContents)
  697. }
  698. }
  699. // AutoTLS can be used as an argument for the `Run` method.
  700. // It will start the Application's secure server using
  701. // certifications created on the fly by the "autocert" golang/x package,
  702. // so localhost may not be working, use it at "production" machine.
  703. //
  704. // Addr should have the form of [host]:port, i.e mydomain.com:443.
  705. //
  706. // The whitelisted domains are separated by whitespace in "domain" argument,
  707. // i.e "iris-go.com", can be different than "addr".
  708. // If empty, all hosts are currently allowed. This is not recommended,
  709. // as it opens a potential attack where clients connect to a server
  710. // by IP address and pretend to be asking for an incorrect host name.
  711. // Manager will attempt to obtain a certificate for that host, incorrectly,
  712. // eventually reaching the CA's rate limit for certificate requests
  713. // and making it impossible to obtain actual certificates.
  714. //
  715. // For an "e-mail" use a non-public one, letsencrypt needs that for your own security.
  716. //
  717. // Note: `AutoTLS` will start a new server for you
  718. // which will redirect all http versions to their https, including subdomains as well.
  719. //
  720. // Last argument is optional, it accepts one or more
  721. // `func(*host.Configurator)` that are being executed
  722. // on that specific host that this function will create to start the server.
  723. // Via host configurators you can configure the back-end host supervisor,
  724. // i.e to add events for shutdown, serve or error.
  725. // An example of this use case can be found at:
  726. // https://github.com/kataras/iris/blob/master/_examples/http-server/notify-on-shutdown/main.go
  727. // Look at the `ConfigureHost` too.
  728. //
  729. // Usage:
  730. // app.Run(iris.AutoTLS("iris-go.com:443", "iris-go.com www.iris-go.com", "mail@example.com"))
  731. //
  732. // See `Run` and `core/host/Supervisor#ListenAndServeAutoTLS` for more.
  733. func AutoTLS(
  734. addr string,
  735. domain string, email string,
  736. hostConfigs ...host.Configurator) Runner {
  737. return func(app *Application) error {
  738. return app.NewHost(&http.Server{Addr: addr}).
  739. Configure(hostConfigs...).
  740. ListenAndServeAutoTLS(domain, email, "letscache")
  741. }
  742. }
  743. // Raw can be used as an argument for the `Run` method.
  744. // It accepts any (listen) function that returns an error,
  745. // this function should be block and return an error
  746. // only when the server exited or a fatal error caused.
  747. //
  748. // With this option you're not limited to the servers
  749. // that iris can run by-default.
  750. //
  751. // See `Run` for more.
  752. func Raw(f func() error) Runner {
  753. return func(app *Application) error {
  754. app.logger.Debugf("HTTP Server will start from unknown, external function")
  755. return f()
  756. }
  757. }
  758. // ErrServerClosed is returned by the Server's Serve, ServeTLS, ListenAndServe,
  759. // and ListenAndServeTLS methods after a call to Shutdown or Close.
  760. //
  761. // A shortcut for the `http#ErrServerClosed`.
  762. var ErrServerClosed = http.ErrServerClosed
  763. // Listen builds the application and starts the server
  764. // on the TCP network address "host:port" which
  765. // handles requests on incoming connections.
  766. //
  767. // Listen always returns a non-nil error.
  768. // Ignore specific errors by using an `iris.WithoutServerError(iris.ErrServerClosed)`
  769. // as a second input argument.
  770. //
  771. // Listen is a shortcut of `app.Run(iris.Addr(hostPort, withOrWithout...))`.
  772. // See `Run` for details.
  773. func (app *Application) Listen(hostPort string, withOrWithout ...Configurator) error {
  774. return app.Run(Addr(hostPort), withOrWithout...)
  775. }
  776. // Run builds the framework and starts the desired `Runner` with or without configuration edits.
  777. //
  778. // Run should be called only once per Application instance, it blocks like http.Server.
  779. //
  780. // If more than one server needed to run on the same iris instance
  781. // then create a new host and run it manually by `go NewHost(*http.Server).Serve/ListenAndServe` etc...
  782. // or use an already created host:
  783. // h := NewHost(*http.Server)
  784. // Run(Raw(h.ListenAndServe), WithCharset("utf-8"), WithRemoteAddrHeader("CF-Connecting-IP"))
  785. //
  786. // The Application can go online with any type of server or iris's host with the help of
  787. // the following runners:
  788. // `Listener`, `Server`, `Addr`, `TLS`, `AutoTLS` and `Raw`.
  789. func (app *Application) Run(serve Runner, withOrWithout ...Configurator) error {
  790. app.Configure(withOrWithout...)
  791. if err := app.Build(); err != nil {
  792. app.logger.Error(err)
  793. return err
  794. }
  795. app.ConfigureHost(func(host *Supervisor) {
  796. host.SocketSharding = app.config.SocketSharding
  797. host.KeepAlive = app.config.KeepAlive
  798. })
  799. app.tryStartTunneling()
  800. if len(app.Hosts) > 0 {
  801. app.logger.Debugf("Application: running using %d host(s)", len(app.Hosts)+1 /* +1 the current */)
  802. }
  803. // this will block until an error(unless supervisor's DeferFlow called from a Task).
  804. err := serve(app)
  805. if err != nil {
  806. app.logger.Error(err)
  807. }
  808. return err
  809. }
  810. // https://ngrok.com/docs
  811. func (app *Application) tryStartTunneling() {
  812. if len(app.config.Tunneling.Tunnels) == 0 {
  813. return
  814. }
  815. app.ConfigureHost(func(su *host.Supervisor) {
  816. su.RegisterOnServe(func(h host.TaskHost) {
  817. publicAddrs, err := tunnel.Start(app.config.Tunneling)
  818. if err != nil {
  819. app.logger.Errorf("Host: tunneling error: %v", err)
  820. return
  821. }
  822. publicAddr := publicAddrs[0]
  823. // to make subdomains resolution still based on this new remote, public addresses.
  824. app.config.vhost = publicAddr[strings.Index(publicAddr, "://")+3:]
  825. directLog := []byte(fmt.Sprintf("• Public Address: %s\n", publicAddr))
  826. app.logger.Printer.Write(directLog) // nolint:errcheck
  827. })
  828. })
  829. }