🚀Server

Server defines a new policy server with corresponding settings

New

This method creates a new Server instance. You can pass ServerOpt functions to provide optional settings when creating a new instance.

Signature

func New(...ServerOpt) Server

Example

s := pps.New()

Changing Server settings

When you already have a Server instance which settings weren't changed using ServerOpt functions, you can use the following methods on the Server instance to subsequently override them.

SetAddr

The SetAddr() method overrides the listening address on the provided Server instance.

Signature

func (*Server) SetAddr(string)

Example

// Create a Server with defaults
s := pps.New()

// Override the listening address
s.SetAddr("127.0.0.1")

SetPort

The SetPort() method will override the listening port on the provided Server instance.

Siganture

func (*Server) SetPort(string)

Example

// Create a Server with defaults
s := pps.New()

// Override the listening port
s.SetPort("1234")

Starting the Server

Starting a policy server with pps is as easy as just executing one method on the Server instance. It is important though, that you provide it with a Context and a custom type that satisfies the pps Handler interface.

Run

Once you have a Server instance ready, all you need is to execute the Run method on it, to start a TCP policy server that is listening on the address/port combination, that you configured in it (Default: 0.0.0.0:10005). The Run() method returns an error in case it wasn't able to start.

Signature

func (*Server) Run(context.Context, Handler) error

Example

// Create your Server instance with defaults
s := pps.New()

// Create a Context of your choice
ctx := context.Background()

// Create an instance of the type that satisfies the Handler interface
h := Hi{}

// Start the server on 0.0.0.0:10005
if err := s.Run(ctx, h); err != nil {
	panic(err)
}

RunWithListener

If you prefer to run your policy service on a different type of listener (i. e. UNIX socket), you can do so by making use of the RunWithListener() method. It works similar to the Run() method, except that you'll have to provide a net.Listener as additional argument.

Signature

func (*Server) RunWithListener(context.Context, Handler, net.Listener) error

Example

// Create your Server instance
s := pps.New()

// We'll create a Context with cancel... just because we can
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// Let's create a UNIX socket listener on /tmp/pps_test_server
l, err := net.Listen("unix", "/tmp/pps_test_server")
if err != nil {
	t.Errorf("failed to create new UNIX socket listener: %s", err)
}

// Again, we require the Handler interface type
h := Hi{}

// ...to finally start our server on /tmp/pps_test_server
if err := s.RunWithListener(ctx, h, l); err != nil {
	t.Errorf("could not run server: %s", err)
}

Contexts

pps allows you to influence specific behaviour of your policy server using vaules in the Context you provide to the Run() or RunWithListener() methods. The context keys that you can set are provided via the CtxKey type of the pps package.

Currently pps supports the following keys:

Property	Type	Description	Default
CtxNoLog	bool	When you run a server, pps by default uses Go's log package to log some errors to STDERR. If you prefer to keep the execution silent without any logging, you can set the CtxNoLog context value to true before you hand your context to the Run*() methods.	nil

Example

// Create your Server instance
s := pps.New()

// And your context with a value
ctx := context.WithValue(context.Background(), pps.CtxNoLog, true)

// Again, we require the Handler interface type
h := Hi{}

// We can now start our server with logging disable
if err := s.Run(ctx, h); err != nil {
		t.Errorf("could not run server: %s", err)
}