Upgrade the documentation, and fireback module generation features

As title.
torabian · Dec 22, 2024 · 0a75327 · 0a75327
1 parent e048653
commit 0a75327
Show file tree

Hide file tree

Showing 208 changed files with 3,105 additions and 1,115 deletions.
diff --git a/docs/docs/definitions/database-support.mdx b/docs/docs/definitions/database-support.mdx
@@ -0,0 +1,55 @@
+---
+title: Database Support
+sidebar_position: 5
+---
+
+Fireback is written based on the GORM library, so it can support connecting out of the box to the following database.
+
+You can update the database config interactively, using `fireback config db`,
+and it would open a prompt and guide you to set the database parameters.
+
+```bash
+ali@alis-MacBook-Pro fireback % fireback config db
+Use the arrow keys to navigate: ↓ ↑ → ← 
+? Database type: 
+  ▸ sqlite (:memory:)
+    sqlite
+    mysql
+    postgres
+```
+
+*Important:* SQLite memory database only lives until the server is closed.
+
+This interactive command would later modify the configuration file, (usually `fireback-configuration.yml` or `yourproject-configuration.yml` file)
+with following possible data:
+
+## Mysql
+
+Connecting to mysql is done by providing normal credentials, and database name.
+
+```yaml
+database:
+  vendor: mysql
+  database: mydb
+  username: root
+  password: root
+  host: localhost
+  port: 3306
+```
+
+## Sqlite
+
+SQLite is a file based database system, and you just need to specifiy the path of the file, and `Vendor` to `sqlite`
+
+In your `config.yml`
+
+```yaml
+database:
+  vendor: sqlite
+  database: /tmp/fireback.db
+```
+
+## Postgres
+
+Postgres is also supported in fireback, (CTE and Pivot queries might be covered in later versions)
+and you can use `fireback config db`
diff --git a/docs/docs/definitions/entities.mdx b/docs/docs/definitions/entities.mdx
@@ -0,0 +1,13 @@
+---
+sidebar_position: 3
+---
+
+# Entities in Fireback
+
+As might be discussed in other documents, entities are tables in database, similar to Entity Framework
+and other ORMs concept of 'entity', which is a table mapped to a class or struct in the programming language.
+
+The major difference between Fireback entities is, it provides functionality by default on top of the entity,
+which could be used directly as http api or cli, without creating much controller. Every entity supposed
+to be able to be created easily, updated, deleted, obey permission role requirements.
+
diff --git a/docs/docs/definitions/http-server.mdx b/docs/docs/definitions/http-server.mdx
@@ -0,0 +1,31 @@
+---
+title: Starting web server
+sidebar_position: 6
+---
+
+Fireback itself, or any projects, microservices built using fireback can serve on http,
+using `fireback start` command. It would lift normal gin http server will all routes.
+
+You can set `PORT` env variable, or set the port in configuration file as well. environment variable
+will override the configuration, which overrides 4500 default port.
+
+```bash
+ali@alis-MacBook-Pro ~ % fireback start
+
+[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
+
+[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
+ - using env:	export GIN_MODE=release
+ - using code:	gin.SetMode(gin.ReleaseMode)
+
+[GIN-debug] GET    /socket.io/*any           --> github.com/gin-gonic/gin.WrapH.func1 (4 handlers)
+[GIN-debug] POST   /socket.io/*any           --> github.com/gin-gonic/gin.WrapH.func1 (4 handlers)
+[GIN-debug] GET    /books                    --> pixelplux.com/fireback/modules/books.HttpQueryBooks (4 handlers)
+...
+```
+
+If you are running fireback itself, you can see an open api document on `http://localhost:4500/docs`
+and also fireback administration ui on `http://localhost:4500`.
+
+For projects built manually you might need to create your own UI and place it into your binary,
+if thats how you would like to distribute UI.
diff --git a/docs/docs/definitions/module3.md b/docs/docs/definitions/module3.md
@@ -45,3 +45,82 @@ and events related to them.
 
 When you define an entity, you often get most of things that you might need to manage them from a administration perspective, you need to create actions on top of them to add your business logic.
 
+## DistinctBy Feature on entities
+
+In Fireback we allow some of entities to be unique, per specific workspace, user or some other conditions.
+This is useful, when you want to make sure only one record per that condition exists on the database.
+For example, you might want to have settings per user, but only per single user.
+
+In such scenarios, you can define `distinctBy` on the entity:
+
+```yaml
+entities:
+    - name: config
+      distinctBy: workspace
+      fields:
+      - name: title
+        type: string
+```
+
+When you make it distinct by workspace, on the entity, WorkspaceId field becomes unique, therefor you cannot have multiple create on the same, and need to use update instead of create.
+
+**Important** Make sure that the `migration apply` has been called if the entity existed before. Migration for unique workspace Id might not occure via gorm migration (which Fireback is using underneath), so you might
+need to manually migration add the unique constraint. For performance reasons, In 1.1.27 Fireback doesn't query
+and only relies on the constraint.
+
+
+## Module3 Messages
+
+Messages, is a powerful yet simple feature of Fireback, which aims to organize the error messages across
+the app. Often in many backends, we do not provide clear, translated error messages for actions.
+
+We recommend to add every possible error message that an backend (cli or http server) return into the module
+definition, and then translate them into different languages on the same place and give explanation.
+
+At the 1.1.27, you cannot extend them from another file, but I think it's useful to be able to keep translation
+of the error messages outside of the project, for those projects are having many languages, but maybe will be provided in later versions of Fireback.
+
+### Define messages on the module:
+
+Consider that the messages are for module at the moment, they will become available for everything,
+there for you need to put the messages of actions also in the the same object.
+
+```yaml
+messages:
+  dataTypeDoesNotExistsInFireback:
+    en: This data type does not exist in fireback. %name %location
+```
+
+When compiled, Fireback will create few objects in Golang which you could use later on (`WorkspacesModule.dyno.go` in this case)
+
+```go
+...
+const (
+	AlreadyConfirmed                   workspacesCode = "AlreadyConfirmed"
+	BodyIsMissing                      workspacesCode = "BodyIsMissing"
+	DataTypeDoesNotExistsInFireback    workspacesCode = "DataTypeDoesNotExistsInFireback"
+...
+```
+
+and Also: 
+
+```go
+
+var WorkspacesMessages = newWorkspacesMessageCode()
+
+func newWorkspacesMessageCode() *workspacesMsgs {
+	return &workspacesMsgs{
+		DataTypeDoesNotExistsInFireback: ErrorItem{
+			"$":  "DataTypeDoesNotExistsInFireback",
+			"en": "This data type does not exist in fireback. %name %location",
+		},
+```
+
+As you see, `$` is the key of the error, which needs to be always present and is equal to uppercase of the key.
+
+Later on, in your actions or other go codes you can use when `IError` is required:
+
+```
+return Create401Error(&WorkspacesMessages.DataTypeDoesNotExistsInFireback, []string{})
+```
+
diff --git a/docs/docs/download-and-install-fireback.mdx b/docs/docs/download-and-install-fireback.mdx
@@ -0,0 +1,45 @@
+---
+title: Download and install fireback
+sidebar_position: 1
+---
+
+## Recommended installers
+
+Fireback comes with MSI intallers for Windows, Packages for mac, and Debian packages for ubuntu.
+Installers will register the binary in the PATH and are recommended way to install:
+
+### Macosx installers:
+
+<a target="_blank" href="https://github.com/torabian/fireback/releases/latest/download/fireback_silicon_arm64.pkg">https://github.com/torabian/fireback/releases/latest/download/fireback_silicon_arm64.pkg</a>
+<a target="_blank" href="https://github.com/torabian/fireback/releases/latest/download/fireback_intel_amd64.pkg">https://github.com/torabian/fireback/releases/latest/download/fireback_intel_amd64.pkg</a>
+
+### Windows msi installers:
+
+<a target="_blank" href="https://github.com/torabian/fireback/releases/latest/download/fireback_win_amd64_installer.msi">https://github.com/torabian/fireback/releases/latest/download/fireback_win_amd64_installer.msi</a>
+<a target="_blank" href="https://github.com/torabian/fireback/releases/latest/download/fireback_win_arm64_installer.msi">https://github.com/torabian/fireback/releases/latest/download/fireback_win_arm64_installer.msi</a>
+
+### Debian installers:
+
+<a target="_blank" href="https://github.com/torabian/fireback/releases/latest/download/fireback-amd64.deb">https://github.com/torabian/fireback/releases/latest/download/fireback-amd64.deb</a>
+<a target="_blank" href="https://github.com/torabian/fireback/releases/latest/download/fireback-arm64.deb">https://github.com/torabian/fireback/releases/latest/download/fireback-arm64.deb</a>
+
+### Vscode extension
+
+Gives you fireback assist, such as Module3 auto completion
+<a target="_blank" href="https://github.com/torabian/fireback/releases/latest/download/fireback-tools.vsix">https://github.com/torabian/fireback/releases/latest/download/fireback-tools.vsix</a>
+
+
+### Using 'go install'
+
+You can install fireback using `go install github.com/torabian/fireback/cmd/fireback@latest`
+This would install it from source, and should be available in `go/bin` folder.
+Sometimes, your `go/bin` folder is not in your path, you need to add it. (Also check the next section)
+
+You might need to add the go/bin to your path, for example mac or linux:
+
+```bash
+echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc && source ~/.bashrc
+```
+
+If your system is reporting that the `fireback` command is missing, make sure you have followed the Go installation guide correctly. Normally, it means that the go/bin directory in your User's home directory is not in the PATH environment variable. You will also normally need to close and reopen any open command prompts so that changes to the environment made by the installer are reflected at the command prompt.
+
diff --git a/docs/docs/passports-module.mdx b/docs/docs/passports-module.mdx
@@ -0,0 +1,41 @@
+---
+title: Passports Introduction
+description: Signup and Signin management through passports
+---
+
+Fireback provides a core user system for every project. Fireback project tends to be complete in itself,
+therefor ABAC solution is built right into it.
+
+For almost every interaction with Fireback or projects built with it, you need to be authenticated. This authentication
+is basically a token, which defines what kind of access level current session has.
+
+Because most of fireabck actions are written in specific workspace by a user, generally all actions of an entity
+are locked to that feature. You can have of course public access scope on an entity, for example public newsletter
+sign up without authentication or some statisics if needed.
+
+## What passport entity is
+
+Passport entity represents a tool such as email address, or phone number, or could be a google login
+to authenticate a user. Passports belong to the root, and modifying them is only other custom actions
+such as signup, change passport and more.
+
+Passports do not have authentication level, they just verify that the user is what who pretends he is, and 
+in theory each user can have multiple passports, they can extra email to their user account or remove, although
+this feature might not be available in current version, database design supports it.
+
+## Passport method
+
+Passport method is another table in the database, which would define what method of authentication are available
+in the project, and modifying it is also root access only. Using passport method, you can define very specific authentication options, remove an option, or specifiy different methods for different countries.
+
+This section is accessible via `fireback passport method` command.
+
+## Login via CLI
+
+After creating a new project - or just installing pure Fireback itself - you need to initialize an environment.
+This could be done by `fireback init` or `./app init` if you are in your own project.
+
+If you continue the prompt questions, they will ask you about a admin user, with a name or last name. This command is independently available on `fireback passport new` function, which would create a user, workspace, assign roles,
+generate a token and authenticate the cli with that. Current authenticated user could be show by `fireback ws view`
+which would export a lot of different details of current user access.
+
diff --git a/go.mod b/go.mod
@@ -52,8 +52,8 @@ require (
 	github.com/yaa110/go-persian-calendar v1.1.5
 	golang.org/x/crypto v0.27.0
 	golang.org/x/exp v0.0.0-20240222234643-814bf88cf225
-	golang.org/x/sync v0.8.0
-	golang.org/x/text v0.18.0
+	golang.org/x/sync v0.10.0
+	golang.org/x/text v0.21.0
 	gopkg.in/yaml.v2 v2.4.0
 	gopkg.in/yaml.v3 v3.0.1
 	gorm.io/driver/mysql v1.5.2
@@ -63,18 +63,24 @@ require (
 )
 
 require (
+	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/bmizerany/pat v0.0.0-20170815010413-6226ea591a40 // indirect
 	github.com/bytedance/sonic v1.11.9 // indirect
 	github.com/bytedance/sonic/loader v0.1.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/charmbracelet/bubbletea v1.2.4 // indirect
+	github.com/charmbracelet/lipgloss v1.0.0 // indirect
+	github.com/charmbracelet/x/ansi v0.6.0 // indirect
+	github.com/charmbracelet/x/term v0.2.1 // indirect
 	github.com/chzyer/readline v1.5.0 // indirect
 	github.com/cloudwego/base64x v0.1.4 // indirect
 	github.com/cloudwego/iasm v0.2.0 // indirect
 	github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
 	github.com/glebarez/go-sqlite v1.21.2 // indirect
@@ -101,16 +107,21 @@ require (
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.8 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/mattn/go-runewidth v0.0.15 // indirect
+	github.com/mattn/go-localereader v0.0.1 // indirect
+	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/mattn/go-sqlite3 v1.14.17 // indirect
 	github.com/mitchellh/colorstring v0.0.0-20190213212951-d06e56a500db // indirect
 	github.com/mitchellh/go-wordwrap v0.0.0-20150314170334-ad45545899c7 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
+	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
+	github.com/muesli/cancelreader v0.2.2 // indirect
+	github.com/muesli/termenv v0.15.2 // indirect
 	github.com/nsf/termbox-go v0.0.0-20190121233118-02980233997d // indirect
 	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
 	github.com/perimeterx/marshmallow v1.1.5 // indirect
@@ -133,7 +144,7 @@ require (
 	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	golang.org/x/arch v0.8.0 // indirect
 	golang.org/x/net v0.29.0 // indirect
-	golang.org/x/sys v0.25.0 // indirect
+	golang.org/x/sys v0.28.0 // indirect
 	golang.org/x/term v0.24.0 // indirect
 	golang.org/x/time v0.5.0 // indirect
 	google.golang.org/protobuf v1.34.2 // indirect