diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60409007..00a4d76a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,6 +64,7 @@ This is the directory structure we use for the project: - `test_e2e/`: Contains all the feature and steps for e2e tests. - `testintegration/`: Contains all the integration tests. - `logger/` *(Go code)*: Contains the logger creation logic. Please don't call it from your own services and code, use the dependency injection system. +- `orm/` *(Go code)*: Contains the code of the orm used by badaas. - `persistance/` *(Go code)*: - `gormdatabase/` *(Go code)*: Contains the logic to create a database. Also contains a go package named `gormzap`: it is a compatibility layer between *gorm.io/gorm* and *github.com/uber-go/zap*. - `models/` *(Go code)*: Contains the models (for a structure to me considered a valid model, it has to embed `badaas/orm.UUIDModel` or `badaas/orm.UIntModel`). diff --git a/README.md b/README.md index 54d7a586..2bdcffe4 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,10 @@ Badaas enables the effortless construction of ***distributed, resilient, highly available and secure applications by design***, while ensuring very simple deployment and management (NoOps). -Badaas provides several key features: - -- **Authentication**: Badaas can authenticate users using its internal authentication scheme or externally by using protocols such as OIDC, SAML, Oauth2... -- **Authorization**: On resource access, Badaas will check if the user is authorized using a RBAC model. -- **Distribution**: Badaas is built to run in clusters by default. Communications between nodes are TLS encrypted using [shoset](https://github.com/ditrit/shoset). -- **Persistence**: Applicative objects are persisted as well as user files. Those resources are shared across the clusters to increase resiliency. -- **Querying Resources**: Resources are accessible via a REST API. -- **Posix compliant**: Badaas strives towards being a good unix citizen and respecting commonly accepted norms. (see [Configuration](#configuration)) -- **Advanced logs management**: Badaas provides an interface to interact with the logs produced by the clusters. Logs are formatted in json by default. +> **Warning** +> BaDaaS is still under development. Each of its components can have a different state of evolution that you can consult in [Features and components](#features-and-components) +- [Features and components](#features-and-components) - [Quickstart](#quickstart) - [Example](#example) - [Step-by-step instructions](#step-by-step-instructions) @@ -19,6 +13,18 @@ Badaas provides several key features: - [Contributing](#contributing) - [License](#license) +## Features and components + +Badaas provides several key features, each provided by a component that can be used independently and has a different state of evolution: + +- **Authentication**(unstable): Badaas can authenticate users using its internal authentication scheme or externally by using protocols such as OIDC, SAML, Oauth2... +- **Authorization**(wip_unstable): On resource access, Badaas will check if the user is authorized using a RBAC model. +- **Distribution**(todo): Badaas is built to run in clusters by default. Communications between nodes are TLS encrypted using [shoset](https://github.com/ditrit/shoset). +- **Persistence**(wip_unstable): Applicative objects are persisted as well as user files. Those resources are shared across the clusters to increase resiliency. To achieve this, BaDaaS uses the [BaDaaS ORM](https://github.com/ditrit/badaas/orm) component. +- **Querying Resources**(unstable): Resources are accessible via a REST API. +- **Posix compliant**(stable): Badaas strives towards being a good unix citizen and respecting commonly accepted norms. (see [Configuration](#configuration)) +- **Advanced logs management**(todo): Badaas provides an interface to interact with the logs produced by the clusters. Logs are formatted in json by default. + ## Quickstart ### Example diff --git a/orm/README.md b/orm/README.md new file mode 100644 index 00000000..68627b09 --- /dev/null +++ b/orm/README.md @@ -0,0 +1,99 @@ +# BaDaaS ORM: Backend and Distribution ORM (Object Relational Mapping) + +BaDaaS ORM is the BaDaaS component that allows for easy persistence and querying of objects. It is built on top of gorm and adds for each entity a service and a repository that allows complex queries without any extra effort. + +BaDaaS ORM can be used both within a BaDaaS application and as a stand-alone application. + +- [Quickstart](#quickstart) + - [Stand-alone Example](#stand-alone-example) + - [BaDaaS Example](#badaas-example) + - [Step-by-step instructions](#step-by-step-instructions) +- [Provided functionalities](#provided-functionalities) + - [Base models](#base-models) + - [CRUDServiceModule](#crudservicemodule) + +## Quickstart + +### Stand-alone Example + +To quickly understand the features provided by badaas-orm, you can head to the [example](https://github.com/ditrit/badaas-orm-example). This example will help you to see how to use badaas-orm and as a template to start your own project. + +### BaDaaS Example + +If you are interested in using badaas-orm within a BaDaaS application you can consult the [example](https://github.com/ditrit/badaas-example) in which besides using the services and repositories provided by badaas-orm, BaDaaS adds a controller that allows the query of objects via an http api. + +### Step-by-step instructions + +Once you have started your project with `go init`, you must add the dependency to BaDaaS: + +```bash +go get -u github.com/ditrit/badaas +``` + +In order to use badaas-orm you will also need to use the following libraries: + +```bash +go get -u github.com/uber-go/fx github.com/uber-go/zap gorm.io/gorm +``` + +First of all, you will need to start your application with `fx`: + +```go +func main() { + fx.New( + // connect to db + fx.Provide(NewGormDBConnection), + // activate badaas-orm + fx.Provide(GetModels), + orm.AutoMigrate, + + // create crud services for models + orm.GetCRUDServiceModule[models.Company](), + orm.GetCRUDServiceModule[models.Product](), + orm.GetCRUDServiceModule[models.Seller](), + orm.GetCRUDServiceModule[models.Sale](), + + // start example data + fx.Provide(CreateCRUDObjects), + fx.Invoke(QueryCRUDObjects), + ).Run() +} +``` + +There are some things you need to provide to the badaas-orm module: + +- `NewGORMDBConnection` is the function that establish the connection to the database where you data will be saved. +- `GetModels` is the function that returns a `orm.GetModelsResult`, to tell badaas-orm which are the models you want to be auto-migrated. + +After that, you can execute the auto-migration with `orm.AutoMigrate` and create the CRUD services to your models using `orm.GetCRUDServiceModule`. + +Finally, you can call your application functions as `CreateCRUDObjects` and `QueryCRUDObjects` where created CRUDServices can be injected to create, read, update and delete your models easily. + +## Provided functionalities + +### Base models + +badaas-orm gives you two types of base models for your classes: `orm.UUIDModel` and `orm.UIntModel`. + +To use them, simply embed the desired model in any of your classes: + +```go +type MyClass struct { + orm.UUIDModel + + // your code here +} +``` + +Once done your class will be considered a **BaDaaS Model**. + +The difference between them is the type they will use as primary key: a random uuid and an auto incremental uint respectively. Both provide date created, edited and deleted (). + +### CRUDServiceModule + +`CRUDServiceModule` provides you a CRUDService and a CRUDRepository for your badaas Model. After calling it as, for example, `orm.GetCRUDServiceModule[models.Company](),` the following can be used by dependency injection: + +- `crudCompanyService orm.CRUDService[models.Company, orm.UUID]` +- `crudCompanyRepository orm.CRUDRepository[models.Company, orm.UUID]` + +These classes will allow you to perform queries using the compilable query system generated with badaas-cli. For details on how to do this visit [badaas-cli docs](github.com/ditrit/badaas-cli/README.md).