Skip to content

Namespace service

The native_namespace is a service for managing namespaces in the entire platform ecosystem. Namespace provides logical separation of the data for modules and services. They can be used, for example, to distinguish customers in the application. After the creation of the namespace, the native_namespace service creates a new openpb_namespace_<name> database so that every new namespace data can be placed in a separate database. On namespace deletion, the service will delete its database, and all the data will be lost.

Interaction examples

Those are several examples of how you can interact with the system from other kernel systems or modules.

Basic communication

In this example we will create new namespace. Then we will check if created namespace exists

package main

import (
    "context"

    native "github.com/slamy-solutions/openbp/modules/native/libs/golang"
    "github.com/slamy-solutions/openbp/modules/native/libs/golang/namespace"
)

const NATIVE_NAMESPACE_URL = "native_namespace:80"

func main() {
    // Connect to the namespace service
    nativeStub := native.NewNativeStub(native.NewStubConfig().WithNamespaceService())
    nativeStub.Connect()
    defer nativeStub.Close()

    // Create new namespace
    nativeStub.Services.Namespace.Create(context.TODO(), &namespace.EnsureNamespaceRequest{
        Name: "mynamespace",
        FullName: "My new namespace :)",
        Descriptions: "I created this namespace just for fun XD"
    })

    // Check if namespace was created
    response, _ := nativeStub.Services.Namespace.Exists(context.TODO(), &namespace.IsNamespaceExistRequest{
        Name:     "mynamespace",
        UseCache: true,
    })

    print(response.Exist)
}
Listen for events

In this example, we will listen for events on the namespace service

package main

import (
    "context"
    "fmt"

    "github.com/nats-io/nats.go"
    native "github.com/slamy-solutions/openbp/modules/native/libs/golang"
    system "github.com/slamy-solutions/openbp/modules/system/libs/golang"
    "github.com/slamy-solutions/openbp/modules/native/libs/golang/namespace"
)


func main() {
    // Connect to the namespace service
    nativeStub := native.NewNativeStub(native.NewStubConfig().WithNamespaceService())
    nativeStub.Connect()
    defer nativeStub.Close()

    // Connect to NATS
    systemStub := system.NewSystemStub(system.NewSystemStubConfig().WithNats())
    systemStub.Connect()
    defer systemStub.Close()

    // Start listen for namespace creation events
    jet, _ := systemStub.Nats.JetStream()
    consumer, _ := jet.AddConsumer("native.namespace.event", &nats.ConsumerConfig{FilterSubject: "native.namespace.event.created", Name: "mymodule.myservice.namespace_consumer"})
    sub, _ := jet.SubscribeSync("", nats.Bind(consumer.Stream, consumer.Name))

    // Create new namespace
    nativeStub.Services.Namespace.Ensure(context.TODO(), &namespace.EnsureNamespaceRequest{
        Name: "mynamespace",
    })

    // Receive event with created namespace
    msg, _ := sub.NextMsg(5 * time.Second)
    var namespaceData namespace.Namespace
    proto.Unmarshal(msg.Data, &namespaceData)
    fmt.Printf("Created [%s] namespace\n", namespaceData.Name)
    msg.Ack()
}

Info

You can connect to the system using other languages than those provided in this example. You will have to manually compile protobuf definitions of this service in the language you want. For more information, please have a look at Use the language you want concept.

Schema

The schema of the namespace is defined using protobuf. Definitions are provided by the native module.

Namespace schema:

Property Type Description
name string Unique short name.
fullName string Full, public name.
description string Arbitrary description.
created timestamp Timestamp when namespace was created
updated timestamp Timestamp when namespace was updated last time
version uint64 Counter that increases on every update of the namespace information

API

Communication with the system is possible using the gRPC interface. Definitions of the interface (proto file) are provided by the native module.

rpc Create(CreateNamespaceRequest) returns (CreateNamespaceResponse) {};

Creates new namespace. Returns error if the namespace with same name already exists.

Parameter name Type Description Required Format
name string Unique name of the namespace. Can't be changed later True Regex ^[A-Za-z0-9]+$. Maximum 32 characters
fullName string Full, public name. Can be changed later. False Maximum 128 characters
description string Arbitrary description. Can be changed later. False Maximum 512 characters

Namespace and the new openbp_namespace_<name> database were successfully created.

Response value Type Description
namespace Namespace Newly created namespace

Info

This response will raise the event on the system_nats. Check the Events section and the specific event for the namespace creation.

Namespace with the same name already exists.

At least one of the parameters has a bad format.

rpc Ensure(EnsureNamespaceRequest) returns (EnsureNamespaceResponse) {};

Creates new namespace if it doesn't exist. Does nothing if the namespace already exists.

Parameter name Type Description Required Format
name string Unique name of the namespace. Can't be changed later True Regex ^[A-Za-z0-9]+$. Maximum 32 characters
fullName string Full, public name. Can be changed later. False Maximum 128 characters
description string Arbitrary description. Can be changed later. False Maximum 512 characters

Namespace was successfully created (or it existed before request). Service created new openbp_namespace_<name> database.

Response value Type Description
namespace Namespace Newly created namespace
created bool Indicates if namespace was created or it already existed before this request

Info

This response will raise the event on the system_nats. Check the Events section and the specific event for the namespace creation.

At least one of the parameters has a bad format.

rpc Update(UpdateNamespaceRequest) returns (UpdateNamespaceResponse) {};

Updates information of the existing namespace.

Parameter name Type Description Required Format
name string Name of the namespace to update True -
fullName string New full, public name False Maximum 128 characters
description string New description. False Maximum 512 characters

Namespace was successfully updated.

Response value Type Description
namespace Namespace Namespace information after the update

Info

This response will raise the event on the system_nats. Check the Events section and the specific event for the namespace update.

Namespace with this name wasn't founded.

At least one of the parameters has a bad format.

rpc Delete(DeleteNamespaceRequest) returns (DeleteNamespaceResponse) {};

Deletes namespace and corresponding database.

Danger

This is very danger operation. Service will delete the entire database and all data of all other services.

Parameter name Type Description
name string Unique name of the namespace to be deleted

Namespace was successfully deleted or wasn't exist. Service has removed the entry from the openbp_global database and deleted openbp_namespace_<name> database.

Response value Type Description
existed bool Indicates if namespace existed before this operation or not

Info

This response will raise an event on the system_nats. Check the Events section and specific events raised on namespace deletion.

rpc Get(GetNamespaceRequest) returns (GetNamespaceResponse) {};

Returns namespace information by its name

Parameter name Type Description
name string Unique name of the namespace to get
useCache bool Tell services if it can use cache in order to optimize response speed.

Tip

Using cache greatly reduces response times. The cache may not be valid under rare conditions. Cache may not be valid only when there are a lot of read/write operations on namespace information simultaneously. In the real system, namespace probably will never change, so it's excellent practice to use cache wherever you can. The invalid cache deletes after some time (60 seconds by default). The system tries to keep the cache up to date, but it cants ensure its validity all the time.

Namespace was founded, and its data was successfully returned.

Response value Type Description
namespace Namespace Namespace information

Service can't find this namespaces. Probably, it doesn't exist.

rpc GetAll(GetAllNamespacesRequest) returns (stream GetAllNamespacesResponse) {};

Gets stream of all namespaces

Request doesn't has parameters. It just returns all the namespaces.

Successfully got a stream of the namespaces.

Response value Type Description
namespace Namespace Namespace information
rpc Exists(IsNamespaceExistRequest) returns (IsNamespaceExistResponse) {};

Checks if namespace with provided name exists

Parameter name Type Description Required
name string Unique name of the namespace to check True
useCache bool Tell services if it can use cache in order to optimize response speed. True

Tip

Using cache greatly reduces response times. Assuming you will delete the namespace only once, it is an outstanding practice to use cache whenever possible. The invalid cache will be deleted after a short time (default is 60 seconds).

Successfully checked if namespace exists.

Response value Type Description
exist bool Namespace exist or not
rpc Stat(GetNamespaceStatisticsRequest) returns (GetNamespaceStatisticsResponse) {};

Get namespace statistics.

Parameter name Type Description
name string Unique name of the namespace to get
useCache bool Tell services if it can use cache in order to optimize response speed.
DB statistic Type Description
objects uint64 Number ob objects stored in the database
dataSize uint64 Total size of the raw data stored (without pre-alocated allocated space and indexes)
totalSize uint64 Total memory usage of the namespace
Response value Type Description
db DB statistics Information about the database usage of this namespace

Namespace wasnt founded. Probably, it doesn't exist.

Events

This service raises events on the system_nats service.

stream subject scheme conditions
native_namespace_event native.namespace.event.created Namespace (protobuf) Namespace was created
native_namespace_event native.namespace.event.updated Namespace (protobuf) Namespace was updated
native_namespace_event native.namespace.event.deleted Namespace (protobuf) Namespace was deleted

Configuration

This service is controlled by environment variables.

Env default description
SYSTEM_DB_URL mongodb://root:example@system_db/admin Mongo DB URL
SYSTEM_CACHE_URL redis://system_cache System_cache redis connection URL
SYSTEM_TELEMETRY_EXPORTER_ENDPOINT system_telemetry:55680 OTEL connector endpoint
SYSTEM_NATS_URL nats://system_nats Nats endpoint