From 5778c57f360cc8bd215683ae8bec749a61f9a468 Mon Sep 17 00:00:00 2001 From: matoval Date: Tue, 16 Jan 2024 20:06:40 -0800 Subject: [PATCH 1/4] Adjust styling to increase readablity --- docs/diagrams/AddListenerBackend.md | 1 + docs/diagrams/Netceptor.md | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 docs/diagrams/Netceptor.md diff --git a/docs/diagrams/AddListenerBackend.md b/docs/diagrams/AddListenerBackend.md index 9d6493ada..a4a75b8cd 100644 --- a/docs/diagrams/AddListenerBackend.md +++ b/docs/diagrams/AddListenerBackend.md @@ -1,4 +1,5 @@ ```mermaid + %%{init: { 'theme':'dark', 'sequence': {'useMaxWidth':false}, 'fontSize': 14 } }%% sequenceDiagram participant Application participant Netceptor diff --git a/docs/diagrams/Netceptor.md b/docs/diagrams/Netceptor.md new file mode 100644 index 000000000..604ceeccf --- /dev/null +++ b/docs/diagrams/Netceptor.md @@ -0,0 +1,7 @@ +```mermaid +sequenceDiagram + participant Application + participant Netceptor + + Application->>+Netceptor: New +``` \ No newline at end of file From e1b1c0ee155fe77d2bf6660b5b6697f61d1653dc Mon Sep 17 00:00:00 2001 From: matoval Date: Thu, 18 Jan 2024 18:02:51 -0800 Subject: [PATCH 2/4] Add main diagram and Netceptor Definition diagram --- docs/diagrams/AddListenerBackend.md | 1 - docs/diagrams/Main.md | 18 +++ docs/diagrams/Netceptor.md | 7 - .../diagrams/Netceptor/NetceptorDefinition.md | 126 ++++++++++++++++++ 4 files changed, 144 insertions(+), 8 deletions(-) create mode 100644 docs/diagrams/Main.md delete mode 100644 docs/diagrams/Netceptor.md create mode 100644 docs/diagrams/Netceptor/NetceptorDefinition.md diff --git a/docs/diagrams/AddListenerBackend.md b/docs/diagrams/AddListenerBackend.md index a4a75b8cd..9d6493ada 100644 --- a/docs/diagrams/AddListenerBackend.md +++ b/docs/diagrams/AddListenerBackend.md @@ -1,5 +1,4 @@ ```mermaid - %%{init: { 'theme':'dark', 'sequence': {'useMaxWidth':false}, 'fontSize': 14 } }%% sequenceDiagram participant Application participant Netceptor diff --git a/docs/diagrams/Main.md b/docs/diagrams/Main.md new file mode 100644 index 000000000..b3d7a7b4c --- /dev/null +++ b/docs/diagrams/Main.md @@ -0,0 +1,18 @@ +```mermaid +flowchart TD +Main[Receptor Main] --> NodeCfgInit[NodeCfg Init] +NodeCfgInit --> Netceptor[Netceptor] +NodeCfgInit --> Workceptor[Workceptor] +NodeCfgInit --> Controlsvc[Controlsvc] +Netceptor --> NetceptorDiagram[Netceptor Diagram] +Netceptor + +click Main "https://github.com/ansible/receptor/blob/devel/cmd/receptor-cl/receptor.go#L49" +click Init "https://github.com/ansible/receptor/blob/devel/pkg/types/main.go#L21" +click Netceptor "https://github.com/ansible/receptor/blob/devel/pkg/netceptor/netceptor.go#L385" +click Controlsvc "https://github.com/ansible/receptor/blob/devel/pkg/controlsvc/controlsvc.go#L161" +click Workceptor "https://github.com/ansible/receptor/blob/devel/pkg/workceptor/workceptor.go#L72" + +click NetceptorDiagram "https://github.com/ansible/receptor/blob/devel/docs/diagrams/Netceptor/Netceptor.md" + +``` \ No newline at end of file diff --git a/docs/diagrams/Netceptor.md b/docs/diagrams/Netceptor.md deleted file mode 100644 index 604ceeccf..000000000 --- a/docs/diagrams/Netceptor.md +++ /dev/null @@ -1,7 +0,0 @@ -```mermaid -sequenceDiagram - participant Application - participant Netceptor - - Application->>+Netceptor: New -``` \ No newline at end of file diff --git a/docs/diagrams/Netceptor/NetceptorDefinition.md b/docs/diagrams/Netceptor/NetceptorDefinition.md new file mode 100644 index 000000000..688ed8109 --- /dev/null +++ b/docs/diagrams/Netceptor/NetceptorDefinition.md @@ -0,0 +1,126 @@ +```mermaid +classDiagram + class Netceptor { + - nodeID: string + - mtu: int + - routeUpdateTime: time.Duration + - serviceAdTime: time.Duration + - seenUpdateExpireTime: time.Duration + - maxForwardingHops: byte + - maxConnectionIdleTime: time.Duration + - workCommands: []WorkCommand + - workCommandsLock: *sync.RWMutex + - epoch: uint64 + - sequence: uint64 + - sequenceLock: *sync.RWMutex + - connLock: *sync.RWMutex + - connections: map[string]*connInfo + - knownNodeLock: *sync.RWMutex + - knownNodeInfo: map[string]*nodeInfo + - seenUpdatesLock: *sync.RWMutex + - seenUpdates: map[string]time.Time + - knownConnectionCosts: map[string]map[string]float64 + - routingTableLock: *sync.RWMutex + - routingTable: map[string]string + - routingPathCosts: map[string]float64 + - listenerLock: *sync.RWMutex + - listenerRegistry: map[string]*PacketConn + - sendRouteFloodChan: chan time.Duration + - updateRoutingTableChan: chan time.Duration + - context: context.Context + - cancelFunc: context.CancelFunc + - hashLock: *sync.RWMutex + - nameHashes: map[uint64]string + - reservedServices: map[string]func(*MessageData) error + - serviceAdsLock: *sync.RWMutex + - serviceAdsReceived: map[string]map[string]*ServiceAdvertisement + - sendServiceAdsChan: chan time.Duration + - backendWaitGroup: sync.WaitGroup + - backendCount: int + - backendCancel: []context.CancelFunc + - networkName: string + - serverTLSConfigs: map[string]*tls.Config + - clientTLSConfigs: map[string]*tls.Config + - clientPinnedFingerprints: map[string][][]byte + - unreachableBroker: *utils.Broker + - routingUpdateBroker: *utils.Broker + - firewallLock: *sync.RWMutex + - firewallRules: []FirewallRuleFunc + + Logger: *logger.ReceptorLogger + + + AddBackend(backend Backend, modifiers ...func(*BackendInfo)) error + + AddFirewallRules(rules []FirewallRuleFunc, clearExisting bool) error + + AddLocalServiceAdvertisement(service string, connType byte, tags map[string]string) + + AddNameHash(name string) uint64 + + AddWorkCommand(command string, secure bool) error + + BackendCount() int + + BackendDone() + + BackendWait() + + CancelBackends() + + Context() context.Context + + Dial(node string, service string, tlscfg *tls.Config) (*Conn, error) + + DialContext(ctx context.Context, node string, service string, tlscfg *tls.Config) (*Conn, error) + + GetClientTLSConfig(name string, expectedHostName string, expectedHostNameType ExpectedHostnameType) (*tls.Config, error) + + GetEphemeralService() string + + GetListenerLock() *sync.RWMutex + + GetListenerRegistry() map[string]*PacketConn + + GetLogger() *logger.ReceptorLogger + + GetNameFromHash(namehash uint64) (string, error) + + GetNetworkName() string + + GetServerTLSConfig(name string) (*tls.Config, error) + + GetServiceInfo(nodeID string, service string) (*ServiceAdvertisement, bool) + + GetUnreachableBroker() *utils.Broker + + Listen(service string, tlscfg *tls.Config) (*Listener, error) + + ListenAndAdvertise(service string, tlscfg *tls.Config, tags map[string]string) (*Listener, error) + + ListenPacket(service string) (PacketConner, error) + + ListenPacketAndAdvertise(service string, tags map[string]string) (PacketConner, error) + + MTU() int + + MaxConnectionIdleTime() time.Duration + + MaxForwardingHops() byte + + NetceptorDone() <-chan struct + + NewAddr(node string, service string) Addr + + NodeID() string + + PathCost(nodeID string) (float64, error) + + Ping(ctx context.Context, target string, hopsToLive byte) (time.Duration, string, error) + + RemoveLocalServiceAdvertisement(service string) error + + RouteUpdateTime() time.Duration + + SeenUpdateExpireTime() time.Duration + + SendMessageWithHopsToLive(fromService string, toNode string, toService string, data []byte, hopsToLive byte) error + + ServiceAdTime() time.Duration + + SetClientTLSConfig(name string, config *tls.Config, pinnedFingerprints [][]byte) error + + SetMaxConnectionIdleTime(userDefinedMaxIdleConnectionTimeout string) error + + SetServerTLSConfig(name string, config *tls.Config) error + + Shutdown() + + Status() Status + + SubscribeRoutingUpdates() chan map[string]string + + Traceroute(ctx context.Context, target string) <-chan *TracerouteResult + - dispatchReservedService(md *MessageData) (bool, error) + - expireSeenUpdates() + - flood(message []byte, excludeConn string) + - forwardMessage(md *MessageData) error + - handleMessageData(md *MessageData) error + - handlePing(md *MessageData) error + - handleRoutingUpdate(ri *routingUpdate, recvConn string) + - handleServiceAdvertisement(data []byte, receivedFrom string) error + - handleUnreachable(md *MessageData) error + - listen(ctx context.Context, service string, tlscfg *tls.Config, advertise bool, adTags map[string]string) (*Listener, error) + - makeRoutingUpdate(suspectedDuplicate uint64) *routingUpdate + - monitorConnectionAging() + - printRoutingTable() + - removeConnection(remoteNodeID string) + - runProtocol(ctx context.Context, sess BackendSession, bi *BackendInfo) error + - sendAndLogConnectionRejection(remoteNodeID string, ci *connInfo, reason string) error + - sendInitialConnectMessage(ci *connInfo, initDoneChan chan bool) + - sendMessage(fromService string, toNode string, toService string, data []byte) error + - sendRejectMessage(ci *connInfo) + - sendRoutingUpdate(suspectedDuplicate uint64) + - sendServiceAd(si *ServiceAdvertisement) error + - sendServiceAds() + - sendUnreachable(toNode string, message *UnreachableMessage) error + - translateDataFromMessage(msg *MessageData) ([]byte, error) + - translateDataToMessage(data []byte) (*MessageData, error) + - translateStructToNetwork(messageType byte, content interface) ([]byte, error) + - updateRoutingTable() + } + +``` \ No newline at end of file From d1312c8f30b2faf97995ea16cb511ad6ff8e4408 Mon Sep 17 00:00:00 2001 From: matoval Date: Thu, 18 Jan 2024 18:04:07 -0800 Subject: [PATCH 3/4] Add _blank to click --- docs/diagrams/Main.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/diagrams/Main.md b/docs/diagrams/Main.md index b3d7a7b4c..b9e6dc771 100644 --- a/docs/diagrams/Main.md +++ b/docs/diagrams/Main.md @@ -7,12 +7,12 @@ NodeCfgInit --> Controlsvc[Controlsvc] Netceptor --> NetceptorDiagram[Netceptor Diagram] Netceptor -click Main "https://github.com/ansible/receptor/blob/devel/cmd/receptor-cl/receptor.go#L49" -click Init "https://github.com/ansible/receptor/blob/devel/pkg/types/main.go#L21" -click Netceptor "https://github.com/ansible/receptor/blob/devel/pkg/netceptor/netceptor.go#L385" -click Controlsvc "https://github.com/ansible/receptor/blob/devel/pkg/controlsvc/controlsvc.go#L161" -click Workceptor "https://github.com/ansible/receptor/blob/devel/pkg/workceptor/workceptor.go#L72" +click Main "https://github.com/ansible/receptor/blob/devel/cmd/receptor-cl/receptor.go#L49" _blank +click Init "https://github.com/ansible/receptor/blob/devel/pkg/types/main.go#L21" _blank +click Netceptor "https://github.com/ansible/receptor/blob/devel/pkg/netceptor/netceptor.go#L385" _blank +click Controlsvc "https://github.com/ansible/receptor/blob/devel/pkg/controlsvc/controlsvc.go#L161" _blank +click Workceptor "https://github.com/ansible/receptor/blob/devel/pkg/workceptor/workceptor.go#L72" _blank -click NetceptorDiagram "https://github.com/ansible/receptor/blob/devel/docs/diagrams/Netceptor/Netceptor.md" +click NetceptorDiagram "https://github.com/ansible/receptor/blob/devel/docs/diagrams/Netceptor/Netceptor.md" _blank ``` \ No newline at end of file From 5a9f0e3e5ccd12762fa21ac2e2e077b6c2a92cf3 Mon Sep 17 00:00:00 2001 From: matoval Date: Mon, 22 Jan 2024 14:01:45 -0800 Subject: [PATCH 4/4] Add InstantiatingNetceptor diagram --- docs/diagrams/AddListenerBackend.md | 1 + docs/diagrams/Main.md | 5 +++-- docs/diagrams/Netceptor/InstantiatingNetceptor.md | 11 +++++++++++ 3 files changed, 15 insertions(+), 2 deletions(-) create mode 100644 docs/diagrams/Netceptor/InstantiatingNetceptor.md diff --git a/docs/diagrams/AddListenerBackend.md b/docs/diagrams/AddListenerBackend.md index 9d6493ada..e926b74d3 100644 --- a/docs/diagrams/AddListenerBackend.md +++ b/docs/diagrams/AddListenerBackend.md @@ -1,4 +1,5 @@ ```mermaid +%%{init: { 'theme':'dark', 'sequence': {'useMaxWidth':false}, 'fontSize': 14 } }%% sequenceDiagram participant Application participant Netceptor diff --git a/docs/diagrams/Main.md b/docs/diagrams/Main.md index b9e6dc771..d02e17bb2 100644 --- a/docs/diagrams/Main.md +++ b/docs/diagrams/Main.md @@ -5,14 +5,15 @@ NodeCfgInit --> Netceptor[Netceptor] NodeCfgInit --> Workceptor[Workceptor] NodeCfgInit --> Controlsvc[Controlsvc] Netceptor --> NetceptorDiagram[Netceptor Diagram] -Netceptor +Netceptor --> InstantiatingNetceptor[Instantiating Netceptor Diagram] click Main "https://github.com/ansible/receptor/blob/devel/cmd/receptor-cl/receptor.go#L49" _blank -click Init "https://github.com/ansible/receptor/blob/devel/pkg/types/main.go#L21" _blank +click NodeCfgInit "https://github.com/ansible/receptor/blob/devel/pkg/types/main.go#L21" _blank click Netceptor "https://github.com/ansible/receptor/blob/devel/pkg/netceptor/netceptor.go#L385" _blank click Controlsvc "https://github.com/ansible/receptor/blob/devel/pkg/controlsvc/controlsvc.go#L161" _blank click Workceptor "https://github.com/ansible/receptor/blob/devel/pkg/workceptor/workceptor.go#L72" _blank click NetceptorDiagram "https://github.com/ansible/receptor/blob/devel/docs/diagrams/Netceptor/Netceptor.md" _blank +click InstantiatingNetceptorDiagram "https://github.com/ansible/receptor/blob/devel/docs/diagrams/Netceptor/InstantiatingNetceptor.md" _blank ``` \ No newline at end of file diff --git a/docs/diagrams/Netceptor/InstantiatingNetceptor.md b/docs/diagrams/Netceptor/InstantiatingNetceptor.md new file mode 100644 index 000000000..579f2aa09 --- /dev/null +++ b/docs/diagrams/Netceptor/InstantiatingNetceptor.md @@ -0,0 +1,11 @@ +```mermaid +%%{init: { 'theme':'dark', 'sequence': {'useMaxWidth':false}, 'fontSize': 14 } }%% +sequenceDiagram + participant Application + participant Netceptor + + Application->>+Netceptor: New + Netceptor-->>-Application: netceptor instance n1 + Application->>+Netceptor:context.Background() + Netceptor-->>-Application:context.Done() +``` \ No newline at end of file