Document config API and provide examples

2 files changed, 85 insertions, 4 deletions

diff --git a/pkg/config/config.go b/pkg/config/config.go
index ba205ce8..5e315094 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -13,6 +13,8 @@ import (
 	"github.com/osrg/gobgp/pkg/server"
 )
 
+// ReadConfigFile parses a config file into a BgpConfigSet which can be applied
+// using InitialConfig and UpdateConfig.
 func ReadConfigFile(configFile, configType string) (*config.BgpConfigSet, error) {
 	return config.ReadConfigfile(configFile, configType)
 }
@@ -160,7 +162,12 @@ func updateNeighbors(ctx context.Context, bgpServer *server.BgpServer, updated [
 	return false
 }
 
-func ApplyInitialConfig(ctx context.Context, bgpServer *server.BgpServer, newConfig *config.BgpConfigSet, isGracefulRestart bool) *config.BgpConfigSet {
+// InitialConfig applies initial configuration to a pristine gobgp instance. It
+// can only be called once for an instance. Subsequent changes to the
+// configuration can be applied using UpdateConfig. The BgpConfigSet can be
+// obtained by calling ReadConfigFile. If graceful restart behavior is desired,
+// pass true for isGracefulRestart. Otherwise, pass false.
+func InitialConfig(ctx context.Context, bgpServer *server.BgpServer, newConfig *config.BgpConfigSet, isGracefulRestart bool) (*config.BgpConfigSet, error) {
 	if err := bgpServer.StartBgp(ctx, &api.StartBgpRequest{
 		Global: config.NewGlobalFromConfigStruct(&newConfig.Global),
 	}); err != nil {
@@ -277,10 +284,16 @@ func ApplyInitialConfig(ctx context.Context, bgpServer *server.BgpServer, newCon
 	addPeerGroups(ctx, bgpServer, addedPg)
 	addDynamicNeighbors(ctx, bgpServer, newConfig.DynamicNeighbors)
 	addNeighbors(ctx, bgpServer, added)
-	return newConfig
+	return newConfig, nil
 }
 
-func UpdateConfig(ctx context.Context, bgpServer *server.BgpServer, c, newConfig *config.BgpConfigSet) *config.BgpConfigSet {
+// UpdateConfig updates the configuration of a running gobgp instance.
+// InitialConfig must have been called once before this can be called for
+// subsequent changes to config. The differences are that this call 1) does not
+// hangle graceful restart and 2) requires a BgpConfigSet for the previous
+// configuration so that it can compute the delta between it and the new
+// config. The new BgpConfigSet can be obtained using ReadConfigFile.
+func UpdateConfig(ctx context.Context, bgpServer *server.BgpServer, c, newConfig *config.BgpConfigSet) (*config.BgpConfigSet, error) {
 	addedPg, deletedPg, updatedPg := config.UpdatePeerGroupConfig(c, newConfig)
 	added, deleted, updated := config.UpdateNeighborConfig(c, newConfig)
 	updatePolicy := config.CheckPolicyDifference(config.ConfigSetToRoutingPolicy(c), config.ConfigSetToRoutingPolicy(newConfig))
@@ -323,5 +336,5 @@ func UpdateConfig(ctx context.Context, bgpServer *server.BgpServer, c, newConfig
 			log.Warn(err)
 		}
 	}
-	return newConfig
+	return newConfig, nil
 }
diff --git a/pkg/config/config_test.go b/pkg/config/config_test.go
new file mode 100644
index 00000000..67ffa5e7
--- /dev/null
+++ b/pkg/config/config_test.go
@@ -0,0 +1,68 @@
+package config
+
+import (
+	"context"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/osrg/gobgp/pkg/server"
+)
+
+// ExampleUpdateConfig shows how InitialConfig can be used without UpdateConfig
+func ExampleInitialConfig() {
+	bgpServer := server.NewBgpServer()
+	go bgpServer.Serve()
+
+	initialConfig, err := ReadConfigFile("gobgp.conf", "toml")
+	if err != nil {
+		// Handle error
+		return
+	}
+
+	isGracefulRestart := true
+	_, err = InitialConfig(context.Background(), bgpServer, initialConfig, isGracefulRestart)
+
+	if err != nil {
+		// Handle error
+		return
+	}
+}
+
+// ExampleUpdateConfig shows how UpdateConfig is used in conjuction with
+// InitialConfig.
+func ExampleUpdateConfig() {
+	bgpServer := server.NewBgpServer()
+	go bgpServer.Serve()
+
+	initialConfig, err := ReadConfigFile("gobgp.conf", "toml")
+	if err != nil {
+		// Handle error
+		return
+	}
+
+	isGracefulRestart := true
+	currentConfig, err := InitialConfig(context.Background(), bgpServer, initialConfig, isGracefulRestart)
+
+	if err != nil {
+		// Handle error
+		return
+	}
+
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGHUP)
+
+	for range sigCh {
+		newConfig, err := ReadConfigFile("gobgp.conf", "toml")
+		if err != nil {
+			// Handle error
+			continue
+		}
+
+		currentConfig, err = UpdateConfig(context.Background(), bgpServer, currentConfig, newConfig)
+		if err != nil {
+			// Handle error
+			continue
+		}
+	}
+}