webezyio 0.0.6

Webezy.io CLI for generating gRPC micro-services

webezy

webezyio is free and open-source project that aims to be a complete framework for developing micro-services projects. The underlying communication protocol is HTTP2 and for serialization and deserialization is protobuf. It utulize those communication protocol, message serialization / deserialization and code generator with gRPC opensource project by google.

Webezy.io has been created to give devlopers quick and structerd way for building gRPC services without pain while keeping thins open for further modifications.

In result we are trying not to restrict the implemantations themselves but instead applying small restrictions on the project structure for well defined, re-usable structure that can be used by many languages and scenarios.

The current supported languages are:

Language	Server	Client	Status
Python	V	V	Stable
Typescript	V	V	Stable
Go	X	X	In-Development
C#.NET	X	X	Planned

Get full explanation and many more details on usage at webezy.io.

The webezyio CLI is a wrapper for WebezyArchitect class which does mainly the processing and execution of creating webezy.jso file.

You can interact with the WebezyArchitect class with two main ways:

• CLI - The most common and easy to get you started creating gRPC services.
• Python API - Will be useful for more compehransive project creation flows and for developers who wants to understand how webezyio works.

Installation

Install from pip

pip install webezyio

Docs

Go to Webezy.io Docs for full explanation.

Useful Resources:

• Awesome gRPC - A curated list of useful resources for gRPC

• API Design Guide From Google - Matches well into gRPC specific design patterns

Tutorials:

• Sample project

Quick Start

Note Please refer to CLI docs for any question you got, also make sute to use the CLI help webezy --help should give you an additional information on every command you may possibly run

To create a new webezy.io project run the following command:

webezy new <YourProject>

Note you can create a new project based on template to get started quickly Sample Python server (Clients are available both in TS + PY)

wz n <YourProject> --template @webezyio/SamplePy

Or the same resources just for Typescript server

wz n <YourProject> --template @webezyio/SampleTs

• For more information see Project Templating

Then you will need to navigate into your project

Note if you didnt specified the --path argument when creating new project by default it will create a project under your current directory

cd <YourProject>

After you are under the new project directory you can go ahead and create webezy.io resources with those simple commands:

Note Please note that every sub-command of generate and new can be shortend with the first letter e.g : wz g p is equivalent to wz generate package

# Generate new package to hold messages
webezy generate package
# Generate new service to hold RPC's (Methods)
webezy generate service
# Generate message under specified package
webezy generate message
# Generate RPC (Method) under specified service
# Same as running `wz g r`
webezy generate rpc

Note Make sure before creating new RPC on service that you have imported at least 1 package to be used by the service. for more information visit -> Package Docs

After you had generated your resources for the project and modified the code (See the docs for more explanation on how to develop your project and make changes Sample Project).

You can now build your project and run your server with those simple commands:

# First build your project
webezy --build
# Then run the server
webezy --run-server

Note you can auto-build your resources if applicable straight when you are generating them with adding --build argument to webezy generate comands.

You can use now your client code that has been autogenerated in your specified language(s) on creating the project.

Pro-Tip: you can always make your commands even shorter with replacing webezy with wz

CLI Usage

Note The CLI has verbose logging system that can be changed accoriding to your needs. we do recommand to keep it to ERROR as default to not overload you with multiple lines for each command - to change the default behaviour run your commands with wz --loglevel DEBUG <sub-command>

Command line interface for the webezyio package build awesome gRPC micro-services. For more information please visit https://www.webezy.io there you can find
additional documentation and tutorials.

positional arguments:
  {new,n,generate,g,ls,package,edit,template}
                        Main modules to interact with Webezy CLI.
    new                 Create new project
    n                   A shortend for new commands
    generate            Generate resources commands
    g                   A shortend for generate commands
    ls                  List resources commands
    package             Attach a package into other services / package
    edit                Edit any webezy.io resource
    template            Create a template from your webezy.json / proto files directory / webezy.template.py

optional arguments:
  -h, --help            show this help message and exit
  --run-server          Run server on current active project
  -v, --version         Display webezyio current installed version
  -e, --expand          Expand optional fields for each resource
  -b, --build           Build webezyio project
  --loglevel {DEBUG,DEBUG,WARNING,ERROR,CRITICAL}
                        Log level
  --verbose             Control on verbose logging
  -u, --undo            Undo last webezy.json modification
  -r, --redo            Redo webezy.json modification, if undo has been made.
  --purge               Purge .webezy/contxt.json file

For more information see - https://www.webezy.io/docs/cli | Created with love by Amit Shmulevitch. 2022 © webezy.io [0.0.4]

wz new

Create new webezy.io projects, can be new blank project or refrenced from already existing template.

positional arguments:
  project               Project name

optional arguments:
  -h, --help            show this help message and exit
  -p PATH, --path PATH  Path for the project root directory
  --port PORT           Port server will run on
  --host HOST           Host name for server
  --domain DOMAIN       Project domain
  --server-language SERVER_LANGUAGE
                        Server language
  --clients [CLIENTS [CLIENTS ...]]
                        Clients language list seprated by spaces
  --build               Clients language list seprated by spaces
  --template {@webezyio/Blank,@webezyio/Sample}
                        Create new project based on template

wz generate

Generate new webezy.io resources under already existing project

positional arguments:
  {s,p,m,r,e}           Generate a webezyio resource from specific resource type, for e.x "s" stands for "service"

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  Name for the resource
  -p PARENT, --parent PARENT
                        Name for the parent resource
  --build               Auto build resources

wz ls

List your project resources

optional arguments:
  -h, --help            show this help message and exit
  --full-name fullName  Display a resource report for specific resoource by passing in a full name, for e.x domain.test.GetTest will return "GetTest" (RPC) which
                        under "test" (service)
  -t {service,package,message,rpc,enum}, --type {service,package,message,rpc,enum}
                        List a webezyio resource from specific resource type

wz package

Mangae your dependencies inside your project

positional arguments:
  source        Package full name
  target        Package path or service name

optional arguments:
  -h, --help    show this help message and exit
  -r, --remove  Package path or service name

Import a package into service

wz package <domain.package.v1> <servicename>

Import a package into another package

wz package <domain.package.v1> <domain.other.v1> 

wz edit

Edit your webezy.io resources

positional arguments:
  name                  Resource full name

optional arguments:
  -h, --help            show this help message and exit
  -a {add,remove,modify}, --action {add,remove,modify}
                        Choose which action to preform on resource
  --sub-action SUB_ACTION
                        Choose which sub-action to preform on resource

Edit a message

wz edit <domain.package.v1.message>

wz template

Create or load a project template

positional arguments:
  path                  Path for webezy.json / protos files directory / webezy.template.py

optional arguments:
  -h, --help            show this help message and exit
  -c, --code            Create a template including code files
  --out-path OUT_PATH   Specify the template file location, defaulted to root project dir
  --template-name TEMPLATE_NAME
                        Specify the template name, defaulted to project package name
  --load                Initalize a template

See Service Templating Section for more information.

Understanding Webezy.io

While it is not nesscesary step to get you started we do recommend to invest few minutes to read an overview of how Webezy.io Built and utulizing gRPC, this high level overview will make you approach some scenarios more easly.

Sub-modules

• builder - A command-pattern module for easy interacting with webezy.json
• cli - A CLI interface module for webezy
• coder - A pluggable API for all code generating methods
• commons - Common modules and methods, such as retrieving and modifying protos

Project Structure

Every webezy.io project should look like the following schema:

Note For simplicity we use for this example 1 service (SampleService) and 1 package (SamplePackage)

# Root dir of your project
my-project/
├─ bin/ # Some executable scripts
├─ clients/ # All clients code in multiple languages if specified
│  ├─ python/
│     ├─ client.py
├─ server/ # Server file
│  ├─ server.py
├─ protos/ # Proto defintions files
│  ├─ SampleService.proto
│  ├─ Samplepackage.proto
├─ service/ # Service file and protos compiled files
│  ├─ protos/
│  │  ├─ SampleService_pb2.py
│  │  ├─ SampleService_pb2_grpc.py
│  │  ├─ SamplePackage_pb2.py
│  │  ├─ SamplePackage_pb2_grpc.py
│  ├─ SampleService.py
├─ .gitignore
├─ README.md

The main compoenent is the webezy.json file which conssisting of all project resources and metadata.

This "Snapshot" of current project state is confined into well structerd json format based on its proto message definition at webezyio.commons.protos.webezy_pb2.py.

message WebezyJson {
    string domain = 1;
    Project project = 2;
    map<string, ServiceDescriptor> services = 3;
    map<string, PackageDescriptor> packages = 4;
    WebezyConfig config = 5;
}

Note See how we utulized protobuffers as main serialization and desrialization in our CLI and core modules

This Json document mainly connsist of 4 components:

• project - All project specific metadata this data is only to be consumed by internal Webezy.io CLI and modules.
• config - Open metadata for various tasks as one of them is to give plugins and other external modules to have context point.
• packages - gRPC driven component for all packages which are centralized place for Enums and Messages under so called "Package" compoenent to be consumed by a "Service".
• services - gRPC driven component for all Services which holds details on RPC's, and Service dependencies which are "Packages" that hold "Messages" that relate to RPC's input and output types.

Service templating

A unique feature allow you to develop locally your project and generate a template or a "Snapshot" of your project resources which can be shared or built on top for versions or branches the generated script currently in Python only. (Future use may include Typescript as well)

This script can be consumed by the Webezy.io CLI to generate your webezy.json and all other directories structure, then you can normally like every webezy project edit or add resources as you wish ! as it was your own services from scratch, allowing you to develop fast and even build your own "Opensource" template which can be reused or refactored as user wish.

Also you can create a new template which holds generated code to WebezyArchitect class based on your already pre-defined services, which we use this technique to distribute services templates that can be installed on different projects.

Create a template from service

webezy template <path/to/webezy.json> --out-path templates --template-name <SomeTemplate>

Load a template for blank service

webezy template <mycustom.template.py> --load

WebezyArchitect API Example

Builtins Templates:

You can use quick start templates that are built in the webezyio.commons.template module as follows:

# A sample python server
wz new <SomeProject> --template @webezyio/SamplePy
# A sample typescript server
wz new <SomeProject> --template @webezyio/SampleTs

SamplePy Template

SampleTs Template

Configure template options

Each template can be configured in webezy.json file under "config" value for easy generating without elborate CLI commands:

{
  "config": {
    "template": {
      "outPath": "template",
      "name": "SamplePy",
      "description": "A basic sample project for webezyio.\nIt is included with examples for all RPC's types and using Enums + Nested Messages, including 'Well Known' messages from google",
      "include": [
        "typescript.ts",
        "python.py",
        "services"
      ],
      "author": "Amit Shmulevitch",
      "includeCode": true
    }
  }
}

With those specifications described above we can now call the template command without any further arguments.

wz template webezy.json

Note the "includeCode" key it can be passed as -c / --code argument to wz template command, it is passed to the exporter of template and includes all files listed under project while searching for "include" list of files and folders then cross checking the "exclude" list against them - Each file listed in the "includes" array will be compressed and attached to the template script.

Warning DO NOT set sensitive information on template code files that are included on template, such as keys and secrets as it will be copied to the template script.

Development

We are welcoming any code contribution and help to maintain and release new fetures as well documenting the library.

See our contirbution page

Builder plugins

Webezy.io allows developer to create thier own modules that inherit from webezyio.builder class, this small modules can be activate on specific hooks and mainly in use with building the proto files, code files and project structure as general.

As you may have noted webezyio has it's Architect class an Builder class which responsible as thier names applies - Design and bring some feel to the project (Architect) \ To construct in reality from the highlevel reprepresentationresntation of resource, to actual working code (Builder)

While currently Architect plugins are not supported (But we do plan to open this module as well).

The Builder Class has been created in plug and play concept for easier and more granluar modules which can be dropped or added without affectively changing how Webezy.io CLI works.

This feature allows you as the developer to further enrich you project creating process with custom files, modules or even changing the projec structure itself to your demands and needs.

See plugins directory for examples

VSCode extension

Webezy.io Developed an Visual Studio Code Extension for developing gRPC service with Webezy.io

The extension main use case is to have a visual represntation and helpers while developing your project resources, allow you to easy navigate inside ever-growing projects and easy command executions with native VSCode GUI.

Warning As the extension is heavily using webezyio CLI it is still dependent on installing the webezyio package and CLI and not to be used as "Stand alone"

Webezy Extension For VSCode

Extension Source Code

---

Created with love by Amit Shmulevitch. 2022 © webezy.io