iris.go 28 KB

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