Actions
You can define actions, which mostly are similar to defining controller on MVC frameworks, which would accept a body, and sends a response, usually as a json format.
Fireback actions will become both accessible using cli
and http
server, it means
fireback is wrappering the actions as general functions (rpc) to be called rather than
traditional http request. This would make every action define both available on cli
and server. You can customize this of course, some actions make no sense to be available
on web or cli.
Defining actions
In any Module3.yml file, you can set array of actions in the root, as well as actions specific to entities.
Here is an example of actions from WorkspaceModule3.yml file:
actions:
- name: importUser
url: /user/import
method: post
description: 'Imports users, and creates their passports, and all details'
in:
fields:
- name: path
type: string
out:
dto: OkayResponseDto
As you see, defining an action is very straight forward, you need to define a name for it, which will be accessible
in golang. url
is also an important aspect, which would make it available to http router. method
is similar
to http methods, and on web server would become that method, and on cli, it would not matter because the name
field would be prefered.
description
is a way to describe the action and would be used on cli, http specs, and some other places which
an explanation of the API is needed.
in
and out
fields do define input and output of the action. They have the same struct underneath, you can set
- entity, which will be indicating an entity is representing the response or request.
- dto, which represents the dto.
- fields, which is basically an array of fields and you can learn how to define them in Fields section.
Module3Action Struct
The Module3Action
struct defines an action that can be used both in HTTP routes and CLI commands. It is less tightly coupled with HTTP-specific definitions and can directly operate on sockets. Below is a detailed explanation of each field in the struct:
Name
- Type:
string
- Description:
The general name of the action. This name is used in Go code generation, request/response bodies, and more. It also serves as the default CLI action name unless overridden byCliName
.
CliName
- Type:
string
- Description:
Overrides the CLI action name. If not specified, theName
field is used (converted to kebab-case if necessary).
ActionAliases
- Type:
[]string
- Description:
A list of CLI aliases for the action. Useful for providing shorter or more convenient command names, e.g.,u
as an alias forupdate
.
Url
- Type:
string
- Description:
The HTTP route for the action, typically in the/api/resource/action
format. If not provided, the action is CLI-only.
Method
- Type:
string
- Description:
Specifies the HTTP method (POST
,GET
,DELETE
, etc.). Additionally, Fireback introduces areactive
method for opening WebSocket connections.
Query
- Type:
[]*Module3Field
- Description:
Type-safe query parameters, accessible with--qs
in CLI and as standard query strings in HTTP.
Description
- Type:
string
- Description:
A detailed description of the action. This is used in comments, API specifications, and other documentation.
Format
- Type:
string
- Description:
Defines the request format. Available formats:POST_ONE
: Single post body.PATCH_ONE
: Single patch body.QUERY
: Returns an array of items, compatible with infinite scroll.PATCH_BULK
: Handles arrays of entities for batch updates.
In
- Type:
*Module3ActionBody
- Description:
Defines the request body, similar to HTTPbody
. SeeModule3ActionBody
for details.
Out
- Type:
*Module3ActionBody
- Description:
Defines the response body. SeeModule3ActionBody
for details.
SecurityModel
- Type:
*SecurityModel
- Description:
Specifies access control, including permissions, tokens, and other security checks. Refer to theSecurityModel
struct for more information.
CliAction
- Type:
func(c *cli.Context, security *SecurityModel) error
- Description:
CLI implementation of the action. Fireback ensures CLI and HTTP functionalities are consistent.
Handlers
- Type:
[]gin.HandlerFunc
- Description:
HTTP implementation of the action using Gin handlers. Fireback handles security checks before invoking these handlers.
Flags
- Type:
[]cli.Flag
- Description:
CLI flags supported by the action. Fireback uses theurfave/cli
library.
ExternFuncName
- Type:
string
- Description:
Used for external function generation (e.g., TypeScript). If left empty, Fireback generates it automatically.
RequestEntity
- Type:
any
- Description:
Represents the request body for RPC code generation in languages like TypeScript and Swift.
ResponseEntity
- Type:
any
- Description:
Represents the response body for RPC code generation.
Action
- Type:
any
- Description:
Represents the core implementation of the action, primarily for code generation purposes.
TargetEntity
- Type:
any
- Description:
Specifies the target entity for the action. Useful for actions like deletion that don't have request or response bodies.
RootModule
- Type:
*Module3
- Description:
Metadata for internal code generation. Links the action to the parent module.
Notes
- Fireback provides consistent functionality across CLI and HTTP by generating code that integrates both.
- The
SecurityModel
ensures secure access to actions, and custom handlers allow for flexible implementation.