Copyright 2019-2023 Demian Harvill
Inventory is a microservice for describing and maintaining an inventory of product items. It is written in Go, and uses gRPC to define and implement it's application programming interface (API). The server requires a JSON Web Token (JWT) generated by the MService microservice for authorization.
As of version v0.9.4, the acctserver can optionally support HTTP Rest requests on a separate port.
Example client usage using the Go command line client (note that any thin client in any language supported by gRPC can be used instead):
invclient create_facility --name homebase
Creates a root facility named by the name parameter. Must have invadmin privileges to create, update or delete a facility.
invclient get_facilities
Get a list of all facilities within the MService account (determined by JWT generated at login).
invclient get_facility_wrapper --id 1
Gets information about the facility, including all nested subares and items within them. The facility_id is returned when the facility is created, but can also be discovered get_facilities.
invclient create_subarea_type --id 3 --name bin
Creates an enumeration for the type of a subarea. Requires invadmin or invrw privileges.
invclient create_subarea --facility 1 --parent 7 --position 1 --subtype 3 --name '3/4 inch grommet'
Creates a new subarea within a facility. If the parent is given, then position gives the index of this subarea within the parent. Requires invadmin or invrw privileges.
invclient get_subareas --id 1
Gets all subareas within a facility.
invclient create_product --name widget --sku W2001-0123 --comment 'mark 1 widget'
Creates a new product. Requires invadmin or invrw privileges.
invclient get_products
Gets a list of all products.
invclient create_item --subarea 4 --itemtype 6 --quantity 1 --product 33
Creates an item in a subarea location. The item has a type (established with create_item_type) and a product (established with create_product)
invclient get_items_by_facility --facility 1
Gets a list of all items in a facility.
Other commands for operations (eg. get, update, delete) can be discovered with
invclient
with no parameters.
The generated JWT uses RSA asymmetric encryption for the public and private keys. These should have been generated when installing the MService microservice; in particular, the inventory server needs access to the jwt_public.pem public key.
In a production environment, the connection between the client and the MService server should be encrypted. This is accomplished with the configuration setting:
tls: true
If using either a public certificate for the server (ie, from LetsEncrypt) or a self-signed certificate, the server need to know the public certificate as well as the private key.
The server configuration is:
cert_file: <location of public or self-signed CA certificate
key_file: <location of private key>
The client configuration needs to know the location of the CA cert_file if using self-signed certificates.
There are MySql scripts in the sql/ directory that create the inventory database (inventory.sql) as well as all the required tables (tb_*.sql). These need to be run on the MySql server to create the database and associated tables.
The persistent data is managed by a MySQL / MariaDB database associated with this microservice.
No data is shared across MService accounts.
The root object is a facility, which describes the campus, building or location for holding a set of items.
The facility is then subdivided (recursively) into smaller locations (subarea) that can hold items or other subareas. For example a building can contain a room, which can contain shelving which can hold bins which can hold items. The type of the subarea is defined by a subarea_type.
An inventory_item is an instance of some product with a given quantity located in a given subarea. The type of the inventory_item is defined by inventory_item_type.
A product defines a potential product with sku, name, etc. A product does not need to have any inventory items (out of stock) but an inventory item must be associated with a product.
As of v0.9.4, the data model can be extended without changing the base data model or server code. There are four entities that have an added (optional) attribute, json_data. These entities are facility, product, subarea and inventory_item. The contents of this attribute are user defined. To assist in this extension, a new entity has been added : entity_schema . This maps an arbitrary schema (defined as json) to an existing entity name.
To build the server:
cd cmd/invserver
go build
The invserver executable can then be run. By default, it expects a YAML configuration file in the same directory named conf.yaml . The location of the configuration file can be changed with an environment variable,INV_CONF , or by the command line flag --conf .
A commented sample configuration file is at cmd/invserver/conf.sample . The locations of the various certificates and keys need to be provided, as well as the database user and password and the MySql connection string. The configuration can also be supplied by enviroment variables (with INV_ prefix) or by command line flags:
invserver -h
Usage:
invserver [flags]
Flags:
--cert_file string Path to certificate file.
--conf string Path to inventory config file. (default "conf.yaml")
--cors_origin string Cross origin sites for REST.
--db_pwd string Database user password.
--db_transport string Database transport string.
--db_user string Database user name.
-h, --help help for invserver
--jwt_pub_file string Path to JWT public certificate.
--key_file string Path to certificate key file.
--log_file string Path to log file.
--port int Port for RPC connections (default 50055)
--rest_port int Port for REST connections
--tls Use tls for connection.
A command line client written in Go is available:
cd cmd/invclient
go install
It also expects a YAML configuration file in the user's home directory, ~/.inventory.config. A commented sample for this file is at cmd/invclient/conf.sample
Running the executable file with no parameters will write usage information to stdout. In particular, all subcommands expect the user to have logged in with Mservice acctclient to establish the JWT. The JWT is also used to determine which account is being used for the command.
Note that the use of the Go invclient is merely a convenience, and not a requirement. Since we are using gRPC, the thin client can be written in any supported language. It can be part of a web or mobile application for example.
As of version v0.9.4, a Go client invclientrest is also available to demonstrate communicating with the server over HTTP Rest instead of Grpc. The usage is the same as for the invclient client.
The inventory microservice relies on the invsvc claim, and the following claim values:
invadmin: administrative access
invrw: read-write access to inventory objects
invro: read-only access to inventory objects
Note that within an account in Mservice, a role must be created to map these claims to a logged-in user.