update documentation +add connectionSet test WIP

Signed-off-by: adisos <[email protected]>

pkg/connection/connection.go

@@ -11,20 +11,25 @@ import (
 	"github.com/np-guard/models/pkg/netset"
 )
 
+// Set captures a set of connections for protocols TCP/UPD/ICMP with their properties (ports/icmp type&code)
 type Set = netset.TransportSet
 
+// NewTCPorUDP returns a set of connections containing the specified protocol (TCP/UDP) and ports
 func NewTCPorUDP(protocol netp.ProtocolString, srcMinP, srcMaxP, dstMinP, dstMaxP int64) *Set {
 	return netset.NewTCPorUDPTransport(protocol, srcMinP, srcMaxP, dstMinP, dstMaxP)
 }
 
+// AllICMP returns a set of connections containing the ICMP protocol with all its possible types,codes
 func AllICMP() *Set {
 	return netset.AllOrNothingTransport(false, true)
 }
 
+// NewTCPSet returns a set of connections containing the TCP protocol with all its possible ports
 func NewTCPSet() *Set {
 	return NewTCPorUDP(netp.ProtocolStringTCP, netp.MinPort, netp.MaxPort, netp.MinPort, netp.MaxPort)
 }
 
+// ICMPConnection returns a set of connections containing the ICMP protocol with specified type,code values
 func ICMPConnection(icmpType, icmpCode *int64) (*Set, error) {
 	icmp, err := netp.ICMPFromTypeAndCode64(icmpType, icmpCode)
 	if err != nil {
@@ -33,10 +38,12 @@ func ICMPConnection(icmpType, icmpCode *int64) (*Set, error) {
 	return netset.NewICMPTransport(icmp), nil
 }
 
+// All returns a set of all protocols (TCP,UPD,ICMP) in the set (with all possible properties values)
 func All() *Set {
 	return netset.AllTransportSet()
 }
 
+// None returns an empty set of protocols connections
 func None() *Set {
 	return netset.AllOrNothingTransport(false, false)
 }

pkg/connection/json.go

@@ -52,6 +52,7 @@ func getCubeAsTCPItems(srcPorts, dstPorts *netset.PortSet, p int64) []spec.TcpUd
 
 type Details spec.ProtocolList
 
+// ToJSON returns a `Details` object for JSON representation of the input connection Set.
 func ToJSON(c *Set) Details {
 	if c == nil {
 		return nil

pkg/netset/connectionset.go

@@ -10,32 +10,42 @@ import (
 	"github.com/np-guard/models/pkg/ds"
 )
 
+// ConnectionSet captures a set of connections for tuples of (src IP range, dst IP range, connection.Set),
+// where connection.Set is a set of TCP/UPD/ICMP with their properties (ports/icmp type&code)
 type ConnectionSet struct {
 	props ds.TripleSet[*IPBlock, *IPBlock, *TransportSet]
 }
 
+// NewConnectionSet returns an empty ConnectionSet
 func NewConnectionSet() *ConnectionSet {
 	return &ConnectionSet{props: ds.NewLeftTripleSet[*IPBlock, *IPBlock, *TransportSet]()}
 }
 
+// Equal returns true is this ConnectionSet captures the exact same set of connections as `other` does.
 func (c *ConnectionSet) Equal(other *ConnectionSet) bool {
 	return c.props.Equal(other.props)
 }
 
+// Copy returns new ConnectionSet object with same set of connections as current one
 func (c *ConnectionSet) Copy() *ConnectionSet {
 	return &ConnectionSet{
 		props: c.props.Copy(),
 	}
 }
 
+// Intersect returns a ConnectionSet object with connection tuples that result from intersecion of
+// this and `other` sets
 func (c *ConnectionSet) Intersect(other *ConnectionSet) *ConnectionSet {
 	return &ConnectionSet{props: c.props.Intersect(other.props)}
 }
 
+// IsEmpty returns true of the ConnectionSet is empty
 func (c *ConnectionSet) IsEmpty() bool {
 	return c.props.IsEmpty()
 }
 
+// Union returns a ConnectionSet object with connection tuples that result from union of
+// this and `other` sets
 func (c *ConnectionSet) Union(other *ConnectionSet) *ConnectionSet {
 	if other.IsEmpty() {
 		return c.Copy()
@@ -48,6 +58,8 @@ func (c *ConnectionSet) Union(other *ConnectionSet) *ConnectionSet {
 	}
 }
 
+// Subtract returns a ConnectionSet object with connection tuples that result from subtraction of
+// `other` from this set
 func (c *ConnectionSet) Subtract(other *ConnectionSet) *ConnectionSet {
 	if other.IsEmpty() {
 		return c.Copy()
@@ -59,3 +71,9 @@ func (c *ConnectionSet) Subtract(other *ConnectionSet) *ConnectionSet {
 func (c *ConnectionSet) IsSubset(other *ConnectionSet) bool {
 	return c.props.IsSubset(other.props)
 }
+
+// ConnectionSetFrom returns a new ConnectionSet object from input src, dst IP-ranges sets ands
+// TransportSet connections
+func ConnectionSetFrom(src, dst *IPBlock, conn *TransportSet) *ConnectionSet {
+	return &ConnectionSet{props: ds.CartesianLeftTriple(src, dst, conn)}
+}

pkg/netset/connectionset_test.go

@@ -0,0 +1,24 @@
+package netset_test
+
+import (
+	"testing"
+
+	"github.com/np-guard/models/pkg/connection"
+	"github.com/np-guard/models/pkg/netset"
+	"github.com/stretchr/testify/require"
+)
+
+func TestConnectionSet(t *testing.T) {
+	src1, _ := netset.IPBlockFromCidr("10.240.10.0/24")
+	dst1, _ := netset.IPBlockFromCidr("10.240.10.0/32")
+	dst2 := src1.Subtract(dst1)
+	conn1 := netset.ConnectionSetFrom(src1, dst1, connection.NewTCPSet())
+	conn2 := netset.ConnectionSetFrom(src1, dst2, connection.NewTCPSet())
+
+	unionConn := conn1.Union(conn2)
+	conn3 := netset.ConnectionSetFrom(src1, src1, connection.NewTCPSet())
+
+	require.True(t, unionConn.Equal(conn3))
+	require.True(t, conn3.Equal(unionConn))
+
+}