mvc

package
v12.2.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 24, 2024 License: BSD-3-Clause Imports: 16 Imported by: 268

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var IgnoreEmbeddedControllers = false

IgnoreEmbeddedControllers is a global variable which indicates whether the controller's method parser should skip converting embedded struct's methods to http handlers.

If no global use is necessary, developers can do the same for individual controllers through the `IgnoreEmbedded` Controller Option on `mvc.Application.Handle` method.

Defaults to false.

View Source 
var Try = hero.Try

Try is a type alias for the `hero#Try`, useful to return a result based on two cases: failure(including panics) and a succeess.

Functions

func NameOf 

func NameOf(v interface{}) string

NameOf returns the package name + the struct type's name, it's used to take the full name of an Controller, the `ControllerActivator#Name`.

Types

type AfterActivation 

type AfterActivation interface {
	Singleton() bool
	DependenciesReadOnly() []*hero.Dependency
	// contains filtered or unexported methods
}

AfterActivation is being used as the only one input argument of a `func(c *Controller) AfterActivation(a mvc.AfterActivation) {}`.

It's being called after the `BeforeActivation`, and after controller's dependencies bind-ed to the fields or the input arguments but before server ran.

It's being used to customize a controller if needed inside the controller itself, it's called once per application.

type Application 

type Application struct {

	// This Application's Name. Keep names unique to each other.
	Name string

	Router      router.Party
	Controllers []*ControllerActivator
	// contains filtered or unexported fields
}

Application is the high-level component of the "mvc" package. It's the API that you will be using to register controllers among with their dependencies that your controllers may expecting. It contains the Router(iris.Party) in order to be able to register template layout, middleware, done handlers as you used with the standard Iris APIBuilder.

The Engine is created by the `New` method and it's the dependencies holder and controllers factory.

See `mvc#New` for more.

func Configure 

func Configure(party router.Party, configurators ...func(*Application)) *Application

Configure creates a new controller and configures it, this function simply calls the `New(party)` and its `.Configure(configurators...)`.

A call of `mvc.New(app.Party("/path").Configure(buildMyMVC)` is equal to 

`mvc.Configure(app.Party("/path"), buildMyMVC)`.

Read more at `New() Application` and `Application#Configure` methods.

func New 

func New(party router.Party) *Application

New returns a new mvc Application based on a "party". Application creates a new engine which is responsible for binding the dependencies and creating and activating the app's controller(s).

Example: `New(app.Party("/todo"))` or `New(app)` as it's the same as `New(app.Party("/"))`.

func (*Application) Clone 

func (app *Application) Clone(party router.Party) *Application

Clone returns a new mvc Application which has the dependencies of the current mvc Application's `Dependencies` and its `ErrorHandler`.

Example: `.Clone(app.Party("/path")).Handle(new(TodoSubController))`.

func (*Application) Configure 

func (app *Application) Configure(configurators ...func(*Application)) *Application

Configure can be used to pass one or more functions that accept this Application, use this to add dependencies and controller(s).

Example: `New(app.Party("/todo")).Configure(func(mvcApp *mvc.Application){...})`.

func (*Application) EnableStructDependents added in v12.2.1 

func (app *Application) EnableStructDependents() *Application

EnableStructDependents will try to resolve the fields of a struct value, if any, when it's a dependent struct value based on the previous registered dependencies.

func (*Application) GetNamespaces 

func (app *Application) GetNamespaces() websocket.Namespaces

GetNamespaces completes the websocket ConnHandler interface. It returns a collection of namespace and events that were registered through `HandleWebsocket` controllers.

func (*Application) Handle 

func (app *Application) Handle(controller interface{}, options ...Option) *Application

Handle serves a controller for the current mvc application's Router. It accept any custom struct which its functions will be transformed to routes.

If "controller" has `BeforeActivation(b mvc.BeforeActivation)` or/and `AfterActivation(a mvc.AfterActivation)` then these will be called between the controller's `.activate`, use those when you want to modify the controller before or/and after the controller will be registered to the main Iris Application.

It returns this mvc Application.

Usage: `.Handle(new(TodoController))`.

Controller accepts a sub router and registers any custom struct as controller, if struct doesn't have any compatible methods neither are registered via `ControllerActivator`'s `Handle` method then the controller is not registered at all.

A Controller may have one or more methods that are wrapped to a handler and registered as routes before the server ran. The controller's method can accept any input argument that are previously binded via the dependencies or route's path accepts dynamic path parameters. The controller's fields are also bindable via the dependencies, either a static value (service) or a function (dynamically) which accepts a context and returns a single value (this type is being used to find the relative field or method's input argument).

func(c *ExampleController) Get() string | (string, string) | (string, int) | int | (int, string | (string, error) | bool | (any, bool) | error | (int, error) | (customStruct, error) | customStruct | (customStruct, int) | (customStruct, string) | Result or (Result, error) where Get is an HTTP Method func.

Default behavior can be changed through second, variadic, variable "options", e.g. Handle(controller, GRPC {Server: grpcServer, Strict: true})

Examples at: https://github.com/kataras/iris/tree/main/_examples/mvc

func (*Application) HandleError 

func (app *Application) HandleError(handler func(ctx *context.Context, err error)) *Application

HandleError registers a `hero.ErrorHandlerFunc` which will be fired when application's controllers' functions returns an non-nil error. Each controller can override it by implementing the `hero.ErrorHandler`.

func (*Application) HandleWebsocket 

func (app *Application) HandleWebsocket(controller interface{}) *websocket.Struct

HandleWebsocket handles a websocket specific controller. Its exported methods are the events. If a "Namespace" field or method exists then namespace is set, otherwise empty namespace. Note that a websocket controller is registered and ran under a specific connection connected to a namespace and it cannot send HTTP responses on that state. However all static and dynamic dependency injection features are working, as expected, like any regular MVC Controller.

func (*Application) Party 

func (app *Application) Party(relativePath string, middleware ...context.Handler) *Application

Party returns a new child mvc Application based on the current path + "relativePath". The new mvc Application has the same dependencies of the current mvc Application, until otherwise specified later manually.

The router's root path of this child will be the current mvc Application's root path + "relativePath".

func (*Application) Register 

func (app *Application) Register(dependencies ...interface{}) *Application

Register appends one or more values as dependencies. The value can be a single struct value-instance or a function which has one input and one output, the input should be an `iris.Context` and the output can be any type, that output type will be bind-ed to the controller's field, if matching or to the controller's methods, if matching.

These dependencies "dependencies" can be changed per-controller as well, via controller's `BeforeActivation` and `AfterActivation` methods, look the `Handle` method for more.

It returns this Application.

Example: `.Register(loggerService{prefix: "dev"}, func(ctx iris.Context) User {...})`.

func (*Application) SetControllersNoLog added in v12.2.0 

func (app *Application) SetControllersNoLog(disable bool) *Application

SetControllersNoLog disables verbose logging for next registered controllers under this App and its children of `Application.Party` or `Application.Clone`.

To disable logging for routes under a Party, see `Party.SetRoutesNoLog` instead.

Defaults to false when log level is "debug".

func (*Application) SetCustomPathWordFunc added in v12.2.0 

func (app *Application) SetCustomPathWordFunc(wordFunc CustomPathWordFunc) *Application

SetCustomPathWordFunc sets a custom function which is responsible to override the existing controllers method parsing.

func (*Application) SetName added in v12.2.0 

func (app *Application) SetName(appName string) *Application

SetName sets a unique name to this MVC Application. Used for logging, not used in runtime yet, but maybe useful for future features.

It returns this Application.

type BaseController 

type BaseController interface {
	BeginRequest(*context.Context)
	EndRequest(*context.Context)
}

BaseController is the optional controller interface, if it's completed by the end controller then the BeginRequest and EndRequest are called between the controller's method responsible for the incoming request.

type BeforeActivation 

type BeforeActivation interface {
	Dependencies() *hero.Container
	// contains filtered or unexported methods
}

BeforeActivation is being used as the only one input argument of a `func(c *Controller) BeforeActivation(b mvc.BeforeActivation) {}`.

It's being called before the controller's dependencies binding to the fields or the input arguments but before server ran.

It's being used to customize a controller if needed inside the controller itself, it's called once per application.

type Code added in v12.2.0 

type Code = hero.Code

Code is a type alias for the `hero#Code`, useful for http error handling in controllers. This can be one of the input parameters of the `Controller.HandleHTTPError`.

type ControllerActivator 

type ControllerActivator struct {

	// initRef BaseController // the BaseController as it's passed from the end-dev.
	Value reflect.Value // the BaseController's Value.
	Type  reflect.Type  // raw type of the BaseController (initRef).

	// BeginHandlers is a slice of middleware for this controller.
	// These handlers will be prependend to each one of
	// the route that this controller will register(Handle/HandleMany/struct methods)
	// to the targeted Party.
	// Look the `Use` method too.
	BeginHandlers context.Handlers
	// contains filtered or unexported fields
}

ControllerActivator returns a new controller type info description. Its functionality can be overridden by the end-dev.

func (*ControllerActivator) Activated added in v12.2.0 

func (c *ControllerActivator) Activated() bool

Activated can be called to skip the internal method parsing.

func (*ControllerActivator) Dependencies 

func (c *ControllerActivator) Dependencies() *hero.Container

Dependencies returns a value which can manage the controller's dependencies.

func (*ControllerActivator) DependenciesReadOnly 

func (c *ControllerActivator) DependenciesReadOnly() []*hero.Dependency

DependenciesReadOnly returns a list of dependencies, including the controller's one.

func (*ControllerActivator) GetRoute 

func (c *ControllerActivator) GetRoute(methodName string) *router.Route

GetRoute returns the first registered route based on the controller's method name. It can be used to change the route's name, which is useful for reverse routing inside views. Custom routes can be registered with `Handle`, which returns the *Route. This method exists mostly for the automatic method parsing based on the known patterns inside a controller.

A check for `nil` is necessary for unregistered methods.

See `GetRoutes` and `Handle` too.

func (*ControllerActivator) GetRoutes 

func (c *ControllerActivator) GetRoutes(methodName string) []*router.Route

GetRoutes returns one or more registered route based on the controller's method name. It can be used to change the route's name, which is useful for reverse routing inside views. Custom routes can be registered with `Handle`, which returns the *Route. This method exists mostly for the automatic method parsing based on the known patterns inside a controller.

A check for `nil` is necessary for unregistered methods.

See `Handle` too.

func (*ControllerActivator) Handle 

func (c *ControllerActivator) Handle(method, path, funcName string, middleware ...context.Handler) *router.Route

Handle registers a route based on a http method, the route's path and a function name that belongs to the controller, it accepts a forth, optionally, variadic parameter which is the before handlers.

Just like `Party#Handle`, it returns the `*router.Route`, if failed then it logs the errors and it returns nil, you can check the errors programmatically by the `Party#GetReporter`.

Handle will add a route to the "funcName".

func (*ControllerActivator) HandleMany 

func (c *ControllerActivator) HandleMany(method, path, funcName string, middleware ...context.Handler) []*router.Route

HandleMany like `Handle` but can register more than one path and HTTP method routes separated by whitespace on the same controller's method. Keep note that if the controller's method input arguments are path parameters dependencies they should match with each of the given paths.

Just like `Party#HandleMany`:, it returns the `[]*router.Routes`. Usage: 

func (*Controller) BeforeActivation(b mvc.BeforeActivation) {
	b.HandleMany("GET", "/path /path1" /path2", "HandlePath")
}

HandleMany will override any routes of this "funcName".

func (*ControllerActivator) Name 

func (c *ControllerActivator) Name() string

Name returns the full name of the controller, its package name + the type name. Can used at both `BeforeActivation` and `AfterActivation`.

func (*ControllerActivator) RelName added in v12.2.0 

func (c *ControllerActivator) RelName() string

RelName returns the path relatively to the main package.

func (*ControllerActivator) Router 

func (c *ControllerActivator) Router() router.Party

Router is the standard Iris router's public API. With this you can register middleware, view layouts, subdomains, serve static files and even add custom standard iris handlers as normally.

This Router is the router instance that came from the parent MVC Application, it's the `app.Party(...)` argument.

Can used at both `BeforeActivation` and `AfterActivation`.

func (*ControllerActivator) Singleton 

func (c *ControllerActivator) Singleton() bool

Singleton returns new if all incoming clients' requests have the same controller instance. This is done automatically by iris to reduce the creation of a new controller on each request, if the controller doesn't contain any unexported fields and all fields are services-like, static.

func (*ControllerActivator) SkipEmbeddedMethods added in v12.2.1 

func (c *ControllerActivator) SkipEmbeddedMethods()

SkipEmbeddedMethods should be ran before controller parsing. It skips all embedded struct's methods conversation to http handlers.

Note that even if the controller overrides the embedded methods they will be still ignored because Go doesn't support this detection so far.

See https://github.com/kataras/iris/issues/2103 for more.

func (*ControllerActivator) SkipMethods added in v12.2.1 

func (c *ControllerActivator) SkipMethods(methodNames ...string)

SkipMethods can be used to individually skip one or more controller's method handlers.

func (*ControllerActivator) Use added in v12.2.0 

func (c *ControllerActivator) Use(handlers ...context.Handler) *ControllerActivator

Use registers a middleware for this Controller. It appends one or more handlers to the `BeginHandlers`. It's like the `Party.Use` but specifically for the routes that this controller will register to the targeted `Party`.

type CustomPathWordFunc added in v12.2.0 

type CustomPathWordFunc func(path, w string, wordIndex int) string

CustomPathWordFunc describes the function which can be passed through `Application.SetCustomPathWordFunc` to customize the controllers method parsing.

type DeprecationOptions added in v12.2.0 

type DeprecationOptions = versioning.DeprecationOptions

DeprecationOptions describes the deprecation headers key-values. Is a type alias for the `versioning#DeprecationOptions`.

See `Deprecated` package-level option.

type Err added in v12.2.0 

type Err = hero.Err

Err is a type alias for the `hero#Err`. It is a special type for error stored in mvc responses or context. It's used for a builtin dependency to map the error given by a previous method or middleware.

type GRPC added in v12.2.0 

type GRPC struct {
	// Server is required and should be gRPC Server derives from google's grpc package.
	Server http.Handler
	// ServiceName is required and should be the name of the service (used to build the gRPC route path),
	// e.g. "helloworld.Greeter".
	// For a controller's method of "SayHello" and ServiceName "helloworld.Greeter",
	// both gRPC and common HTTP request path is: "/helloworld.Greeter/SayHello".
	//
	// Tip: the ServiceName can be fetched through proto's file descriptor, e.g.
	// serviceName := pb.File_helloworld_proto.Services().Get(0).FullName().
	ServiceName string

	// When Strict option is true then this controller will only serve gRPC-based clients
	// and fires 404 on common HTTP clients.
	Strict bool
}

GRPC registers a controller which serves gRPC clients. It accepts the controller ptr to a struct value, the gRPCServer itself, and a strict option which is explained below.

The differences between an GRPC-based controller and a common one are: HTTP verb: only POST (Party.AllowMethods can be used for more), method parsing is disabled: path is the function name as it is, if 'strictMode' option is true then this controller will only serve gRPC-based clients and fires 404 on common HTTP clients, otherwise HTTP clients can send and receive JSON (protos contain json struct fields by-default).

func (GRPC) Apply added in v12.2.0 

func (g GRPC) Apply(c *ControllerActivator)

Apply parses the controller's methods and registers gRPC handlers to the application.

type Option added in v12.2.0 

type Option interface {
	Apply(*ControllerActivator)
}

Option is an interface which does contain a single `Apply` method that accepts a `ControllerActivator`. It can be passed on `Application.Handle` method to mdoify the behavior right after the `BeforeActivation` state.

See `GRPC` package-level structure and `Version` package-level function too.

type OptionFunc added in v12.2.0 

type OptionFunc func(*ControllerActivator)

OptionFunc is the functional type of `Option`. Read `Option` docs. 

var IgnoreEmbedded OptionFunc = func(c *ControllerActivator) {
	c.SkipEmbeddedMethods()
}

IgnoreEmbedded is an Option which can be used to ignore all embedded struct's method handlers. Note that even if the controller overrides the embedded methods they will be still ignored because Go doesn't support this detection so far. For global affect, set the `IgnoreEmbeddedControllers` package-level variable to true.

func Deprecated added in v12.2.0 

func Deprecated(options DeprecationOptions) OptionFunc

Deprecated marks a specific Controller as a deprecated one. Deprecated can be used to tell the clients that a newer version of that specific resource is available instead.

func Version added in v12.2.0 

func Version(version string) OptionFunc

Version returns a valid `Option` that can be passed to the `Application.Handle` method. It requires a specific "version" constraint for a Controller, e.g. ">1.0.0 <=2.0.0".

Usage: 

m := mvc.New(dataRouter)
m.Handle(new(v1Controller), mvc.Version("1.0.0"), mvc.Deprecated(mvc.DeprecationOptions{}))
m.Handle(new(v2Controller), mvc.Version("2.3.0"))
m.Handle(new(v3Controller), mvc.Version(">=3.0.0 <4.0.0"))
m.Handle(new(noVersionController))

See the `versioning` package's documentation for more information on how the version is extracted from incoming requests.

Note that this Option will set the route register rule to `RouteOverlap`.

func (OptionFunc) Apply added in v12.2.0 

func (opt OptionFunc) Apply(c *ControllerActivator)

Apply completes the `Option` interface.

type Response 

type Response = hero.Response

Response is a type alias for the `hero#Response`, useful for output controller's methods.

type Result 

type Result = hero.Result

Result is a type alias for the `hero#Result`, useful for output controller's methods.

type View 

type View = hero.View

View is a type alias for the `hero#View`, useful for output controller's methods.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.