Your first service

While 1Backend itself is written in Go, services that run on 1Backend can be written in any language. A service only needs a few things to fully function:

• Register a user account, just like a human user. For details, see the User Svc.
• Register its instance in the registry so 1Backend knows where to route requests.

A Go example

The following Go service demonstrates these steps:

• Registers itself as a user with the slug skeleton-svc
• Registers or updates its URL (http://127.0.0.1:9311) in the Registry.

You may notice that the following code uses a "Go SDK," but it's simply a set of convenience functions built on top of the 1Backend API. 1Backend is language-agnostic and can be used with any language, even if no SDK is available in the repository.

// <!-- INCLUDE: ../../../examples/go/services/basic/internal/basic_service.go -->
package basicservice

import (
	"context"
	"net/http"
	"os"

	openapi "github.com/1backend/1backend/clients/go"
	basic "github.com/1backend/1backend/examples/go/services/basic/internal/types"
	sdk "github.com/1backend/1backend/sdk/go"
	"github.com/1backend/1backend/sdk/go/auth"
	"github.com/1backend/1backend/sdk/go/boot"
	"github.com/1backend/1backend/sdk/go/client"
	"github.com/1backend/1backend/sdk/go/datastore"
	"github.com/1backend/1backend/sdk/go/infra"
	"github.com/1backend/1backend/sdk/go/middlewares"
	"github.com/gorilla/mux"
	"github.com/pkg/errors"
)

const RolePetManager = "basic-svc:pet:manager"

type BasicService struct {
	Options *Options

	token            string
	userSvcPublicKey string

	dataStoreFactory infra.DataStoreFactory

	petsStore       datastore.DataStore
	credentialStore datastore.DataStore

	Router *mux.Router
}

type Options struct {
	Test      bool
	ServerUrl string
	SelfUrl   string
}

func NewService(options *Options) (*BasicService, error) {
	if options.ServerUrl == "" {
		options.ServerUrl = os.Getenv("OB_SERVER_URL")
	}
	if options.ServerUrl == "" {
		options.ServerUrl = "http://127.0.0.1:58231"
	}
	if options.SelfUrl == "" {
		options.SelfUrl = os.Getenv("OB_SELF_URL")
	}

	dconf := infra.DataStoreConfig{}
	if options.Test {
		dconf.TablePrefix = sdk.Id("t")
	}

	service := &BasicService{
		Options: options,
	}

	dsf, err := infra.NewDataStoreFactory(dconf)
	if err != nil {
		return nil, errors.Wrap(err, "cannot create datastore factory")
	}
	service.dataStoreFactory = dsf

	petStore, err := dsf.Create("basicSvcPets", &basic.Pet{})
	if err != nil {
		return nil, err
	}
	service.petsStore = petStore

	service.registerAccount()
	service.registerRoutes()

	return service, nil
}

func (service *BasicService) Start() error {
	client := client.NewApiClientFactory(service.Options.ServerUrl).
		Client(client.WithToken(service.token))

	_, _, err := client.RegistrySvcAPI.
		RegisterInstance(context.Background()).
		Body(openapi.RegistrySvcRegisterInstanceRequest{
			Url: service.Options.SelfUrl,
		}).Execute()
	if err != nil {
		return errors.Wrap(err, "cannot register instance")
	}

	return nil
}

func (service *BasicService) registerAccount() error {
	credentialStore, err := service.dataStoreFactory.Create("basicSvcCredentials", &auth.Credential{})
	if err != nil {
		return errors.Wrap(err, "cannot create credential store")
	}
	service.credentialStore = credentialStore

	obClient := client.NewApiClientFactory(service.Options.ServerUrl).Client()
	token, err := boot.RegisterServiceAccount(
		obClient.UserSvcAPI,
		"basic-svc",
		"Basic Svc",
		service.credentialStore,
	)
	if err != nil {
		return errors.Wrap(err, "cannot register service")
	}
	service.token = token.Token

	obClient = client.NewApiClientFactory(service.Options.ServerUrl).
		Client(client.WithToken(service.token))

	_, _, err = obClient.RegistrySvcAPI.
		RegisterInstance(context.Background()).
		Body(openapi.RegistrySvcRegisterInstanceRequest{
			Url: service.Options.SelfUrl,
		}).Execute()
	if err != nil {
		return errors.Wrap(err, "cannot register instance")
	}

	pk, _, err := obClient.
		UserSvcAPI.GetPublicKey(context.Background()).
		Execute()
	if err != nil {
		return err
	}
	service.userSvcPublicKey = pk.PublicKey

	return nil
}

func (service *BasicService) registerRoutes() {
	mws := []middlewares.Middleware{
		middlewares.ThrottledLogger,
		middlewares.Recover,
		middlewares.CORS,
		middlewares.GzipDecodeMiddleware,
	}
	appl := applicator(mws)

	service.Router = mux.NewRouter()

	service.Router.HandleFunc("/basic-svc/pet", appl(func(w http.ResponseWriter, r *http.Request) {
		service.SavePet(w, r)
	})).
		Methods("OPTIONS", "PUT")

	service.Router.HandleFunc("/basic-svc/pets", appl(func(w http.ResponseWriter, r *http.Request) {
		service.ListPets(w, r)
	})).
		Methods("OPTIONS", "POST")
}

func applicator(
	mws []middlewares.Middleware,
) func(http.HandlerFunc) http.HandlerFunc {
	return func(h http.HandlerFunc) http.HandlerFunc {
		for _, middleware := range mws {
			h = middleware(h)
		}

		return h
	}
}
// <!-- /INCLUDE -->

Just make sure you run it with the appropriate envars:

OB_SERVER_URL=http://127.0.0.1:58231 OB_SELF_URL=http://127.0.0.1:9311 go run main.go

Once it's running you will be able to call the 1Backend server proxy and that will proxy to your skeleton service:

# 127.0.0.1:58231 here is the address of the 1Backend server
$ curl 127.0.0.1:58231/skeleton-svc/hello
{"hello": "world"}

This is so you don't have to expose your skeleton service to the outside world, only your 1Backend server.

Let's recap how the proxying works:

• Service registers an account, acquires the skeleton-svc slug.
• Service calls the 1Backend Registry Svc to tell the system an instance of the Skeleton service is available under the URL http://127.0.0.1:9311
• When you curl the 1Backend server with a path like 127.0.0.1:58231/skeleton-svc/hello, the first section of the path will be a user account slug. The daemon checks what instances are owned by that slug and routes the request to one of the instances.

$ oo instance ls
ID                URL                     STATUS    OWNER SLUG       LAST HEARTBEAT
inst_eHFTNvAlk9   http://127.0.0.1:9311   Healthy   skeleton-svc     10s ago

Things to understand

Instance registration

Like most other things on the platform, service instances become owned by a user account slug. When the skeleton service calls RegisterInstance, the host will be associated with the skeleton-svc slug.

Updates to this host won't be possible unless the caller is the skeleton service (or the caller is an admin). The service becomes the owner of that URL essentially.

This is the same ownership model like in other parts of the 1Backend system.