Developing a new platform service

[jrschumacher]

Needs coverage

• wellknown
• readiness check

Developing a new platform service

This guide will help you to develop a new service within the platform. The platform is focused on a modular binary architecture, so the goal of the service is isolation while also getting the benefits of a shared platform.

Structure

OpenTDF services are located under the service directory. Each service should have a unique directory name, which is expected to relate to the service namespace.

Service Namespace

A service namespace is a unique identifier for the service. It is used to identify the service in the platform and to enable multiple gRPC services to be rolled up into a single service.

The namespace should be a unique identifier for the service. It should be a single word, all lowercase, and should not contain any special characters. It should be the same as the directory name for the service.

Registration

Services are registered with the platform using the service.RegisterService function. This function expects to be given a serviceregistry.Registration object.

platform/service/pkg/serviceregistry/serviceregistry.go

Lines 48 to 55 in 459e82a

	type Registration struct {
	Namespace string
	ServiceDesc *grpc.ServiceDesc
	RegisterFunc RegisterFunc
	// Optional to specify if the service requires a database connection
	DB DBRegister
	}

The goal of the registration is to define how your service should function so that during the sub-service start process, the platform can start the service as expected.

Config

Services utilize the ServiceConfig struct. This struct has some pre-defined properties and will dump anything else into ExtraProps.

platform/service/pkg/serviceregistry/serviceregistry.go

Lines 21 to 25 in 192ff6d

	type ServiceConfig struct {
	Enabled bool `yaml:"enabled"`
	Remote RemoteServiceConfig `yaml:"remote"`
	ExtraProps map[string]interface{} `json:"-" mapstructure:",remain"`
	}

To use this one can access it via the Config param in the RegistrationParams. By using this we can access our config params via the map[string]interface{} or we could map this to a custom config stuct

type ExampleServiceConfig struct {
	*config.ServiceConfig

	myString string
	myBool   bool
}

type ExampleService struct {
	example.UnimplementedExampleServiceServer

	config *config.ServiceConfig
}

func NewRegistration() serviceregistry.Registration {
	// ...
	RegisterFunc: func(srp serviceregistry.RegistrationParams) (any, serviceregistry.HandlerServer) {
		// by adding the sdk to the service we can now use it in our handlers
		svc := ExampleService{
			config: config.ServiceConfig
		}
	
		return &svc, func(ctx context.Context, mux *runtime.ServeMux, server any) error {
			// ... start the server and return handler (see below)
		}
	}
	// ...
}

SDK usage

Every service has access to a shared instance of the SDK. This instance utilizes gRPC interprocess-communication, and it is highly advised to use this rather than generating a new SDK connection. The main benefit of using this SDK is that the platform will manage this for you.

Benefits of using bundled SDK:

• platform manages connection
• no need for a config mapping the platform endpoint
• supports monolith and microservice deployment without service needing to know
• with IPC doesn't leave memory or service mesh (depending on deployment)

The SDK is returned as part of the serviceregistry.RegistrationParams

type ExampleService struct {
	example.UnimplementedExampleServiceServer
	sdk *sdk.SDK
}

func NewRegistration() serviceregistry.Registration {
	// ...
	RegisterFunc: func(srp serviceregistry.RegistrationParams) (any, serviceregistry.HandlerServer) {
		// by adding the sdk to the service we can now use it in our handlers
		svc := ExampleService{
			sdk: srp.SDK
		}
	
		return &svc, func(ctx context.Context, mux *runtime.ServeMux, server any) error {
			// ... start the server and return handler (see below)
		}
	}
	// ...
}

Database usage

The platform utilizes Postgres for its database needs. There are times when a service needs access to a database to ensure persistence of one form or another. As with our other principles, this needs to be managed by the service, but facilitated by the platform.

Each service will be scoped to its own schema in the form of <platform_name>_<service_namespace>. Where the default platform name is opentdf and the service namespace is example the schema will be opentdf_example.

Scoping services to schemas will help to reduce the risk of services interacting with data outside of contracts (protos and generated SDKs).

Warning

Currently multiple connection pools will be created to the same database client. Enhancement and prevention of performance issues is captured in #681

Registration

Database registration is simple through the use of the serviceregistry.DBRegister type.

platform/service/pkg/serviceregistry/serviceregistry.go

Lines 42 to 46 in 459e82a

	type DBRegister struct {
	Required bool
	// Required to support automatic migrations
	Migrations *embed.FS
	}

Migrations

Database migrations are enabled through two libraries

• embed to bundle the sql with the sourcecode
• presley/goose to write the migration files

Migrations can be managed without installing goose locally through the opentdf cmd arguments

> go run ./service migrate
Run database migrations

Usage:
  opentdf migrate [command]

Available Commands:
  down        Run database migration down one version
  status      Show the status of the database migrations
  up          Run database migrations up to the latest version

Well Known

TBD

Readiness Check

TBD

---

Resources

Examples

gRPC service

This is a minimal service registration which

// github.com/opentdf/platform/service/example/example.go
package example

import (
	"fmt"

	"github.com/opentdf/platform/protocol/go/example"
	"github.com/opentdf/platform/service/pkg/serviceregistry"
)

type ExampleService struct {
	example.UnimplementedExampleServiceServer
}

func NewRegistration() serviceregistry.Registration {
	return serviceregistry.Registration{
		ServiceDesc: &example.ExampleService_ServiceDesc,
		RegisterFunc: func(srp serviceregistry.RegistrationParams) (any, serviceregistry.HandlerServer) {
			return &ExampleService{}, func(ctx context.Context, mux *runtime.ServeMux, server any) error {
				if srv, ok := server.(example.ExampleServiceServer); !ok {
					return fmt.Errorf("failed to assert server as example.ExampleServiceServer")
				}
				return example.RegisterExamnpleServiceHandlerServer(ctx, mux, srv)
			}
		},
	}
}

gRPC service with Database

// github.com/opentdf/platform/service/example/example.go
package example

import (
	"embed"
	"fmt"

 	"github.com/opentdf/platform/protocol/go/example"
	"github.com/opentdf/platform/service/pkg/serviceregistry"
)

// go:embed db/migrations/*.sql
var migrations embed.FS

type ExampleService struct {
	example.UnimplementedExampleServiceServer
}

func NewRegistration() serviceregistry.Registration {
	return serviceregistry.Registration{
		ServiceDesc: &example.ExampleService_ServiceDesc,
		DB: serviceregistry.DBRegister{
			Required:   true
			Migrations: migrations
		},
		RegisterFunc: func(srp serviceregistry.RegistrationParams) (any, serviceregistry.HandlerServer) {
			return &ExampleService{}, func(ctx context.Context, mux *runtime.ServeMux, server any) error {
				if srv, ok := server.(example.ExampleServiceServer); !ok {
					return fmt.Errorf("failed to assert server as example.ExampleServiceServer")
				}
				return example.RegisterExamnpleServiceHandlerServer(ctx, mux, srv)
			}
		},
	}
}

Roll-up registration

This example shows how one might want to roll-up services if there are many gRPC services under a namespace.

// github.com/opentdf/platform/service/examplerollup/example.go
package policy

import (
	"embed"

	"github.com/opentdf/platform/service/pkg/serviceregistry"
	"github.com/opentdf/platform/service/examplerollup/ex1"
	"github.com/opentdf/platform/service/examplerollup/ex2"
)

// go:embed db/migrations/*.sql
var migrations embed.FS

func NewRegistrations() []serviceregistry.Registration {
	registrations := []serviceregistry.Registration{}
	namespace := "examplerollup"
	dbRegister := serviceregistry.DBRegister{
		Required:   true,
		Migrations: migrations,
	}

	for _, r := range []serviceregistry.Registration{
		ex1.NewRegistration(),
		ex2.NewRegistration(),
	} {
		r.Namespace = namespace
		r.DB = dbRegister
		registrations = append(registrations, r)
	}

	return registrations
}

HTTP-only service

Warning

It is advised to use the grpc-gateway to generate an HTTP interface rather than rolling an HTTP-only service

This example shows how to register an HTTP-only service.

type ExampleHTTPOnlyServiceInterface interface{}

type ExampleHTTPOnlyService struct {
	srp serviceregistry.RegistrationParams
}

func (s *ExampleHTTPOnlyService) GetHandler(w http.ResponseWriter, r *http.Request, pathParams map[string]string) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(interface{
		"method": r.Method,
		"url": r.URL.String(),
	})
}

func (s *ExampleHTTPOnlyService) GetHandler(w http.ResponseWriter, r *http.Request, pathParams map[string]string) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(interface{
		"method": r.Method,
		"url": r.URL.String(),
		"content-length": r.ContentLength,
	})
}

func NewRegistration() serviceregistry.Registration {
	return serviceregistry.Registration{
		Namespace: "example-http-only",
		ServiceDesc: &grpc.ServiceDesc{
			ServiceName: "example-http-only",
			HandlerType: (*ExampleHTTPOnlyServiceInterface)(nil),
		},
		RegisterFunc: func(srp serviceregistry.RegistrationParams) (any, serviceregistry.HandlerServer) {
			return ExampleHTTPOnlyService{}, func(ctx context.Context, mux *runtime.ServeMux, server any) error {
				// Service Endpoints
				servicePaths := []ServicePath{
					{
						Path:    "/example,
						Method:  "GET",
						Handler: server.(*ExampleHTTPOnlyService).GetHandler,
					},
					{
						Path:    "/example",
						Method:  "POST",
						Handler: server.(*ExampleHTTPOnlyService).PostHandler,
					},
				}

				// Register service endpoints
				for _, path := range servicePaths {
					err := mux.HandlePath(path.Method, path.Path, path.Handler)
					if err != nil {
						return err
					}
				}

				return nil
			}
		},
	}
}

Lifecycle

flowchart TD

	subgraph otdf [OpenTDF]
	S --> REG
	REG --> O_BOOT_S1
    O_BOOT_S1 -- read service registrations --> O_BOOT_S1
	O_BOOT_S1 ----> O_BOOT_S2
	O_BOOT_S2 -- load config --> O_BOOT_S2
    O_BOOT_S2 -- for each service --> IF_ENABLED{Is enabled in config?}

	IF_ENABLED -->|Yes| IF_DB{Req DB?}
	IF_ENABLED -->|No| SKIP

	IF_DB -->|Yes| IF_DB_AUTOMIG{Config runMigration?}
	IF_DB -->|No| O_WK

	O_WK --> O_REDI
	O_REDI --> E

	subgraph db
		direction LR

		IF_DB_AUTOMIG -->|Yes| O_DB_MIG
		IF_DB_AUTOMIG -->|No| O_WK
	end

	O_DB --> O_WK
	

	end

	subgraph user [User Setup]
	U --> DFN
	U --> REG
	end
	

	DFN[Define New Registration]
	REG[Register Service]

	O_BOOT_S1[Stage 1]
	O_BOOT_S2[Stage 2]
	O_REG[OpenTDF Register Service]
	O_START[OpenTDF Start Service]
	O_DB[Register Database]
	O_DB_MIG[Run db migration]

	O_WK[Define Wellknown Config]
	O_REDI[Define Readiness Checks]

	SKIP((Skip))
	S((▶))
	E((⏹))

Loading