Golang के लिए Zeek Broker websocket interface लाइब्रेरी

यह लाइब्रेरी Zeek Broker websocket इंटरफ़ेस को लागू करती है।

Zeek और Go प्रकारों के बीच उचित मैपिंग के साथ सहायक फ़ंक्शन प्रदान किए गए हैं।

उपयोग

लाइब्रेरी में दो पैकेज हैं:

encoding

encoding, Zeek प्रकारों को दर्शाने के लिए रिकर्सिव JSON-आधारित डेटा संरचना का मॉडल बनाता है (Data struct), साथ ही Zeek इवेंट्स और त्रुटि संदेशों का Broker एन्कोडिंग (DataMessage struct)। इन संरचनाओं का उपयोग सीधे किया जा सकता है (और कुछ मामलों में अवश्य किया जाना चाहिए) (अगले अनुभाग में सब्सक्रिप्शन उदाहरण देखें), लेकिन कुछ सहायक फ़ंक्शन संदेश बनाना अधिक सुविधाजनक बनाते हैं। Zeek string मैन्युअल रूप से बनाने के लिए:

zeekString := encoding.Data{
    DataType:  encoding.TypeString,
    DataValue: "foo",
}

...या हेल्पर के माध्यम से:

zeekString := encoding.String("foo")

विशेष रूप से vector हेल्पर एक वेरिएडिक फ़ंक्शन है जो encoding.Data स्वीकार करता है:

zeekVector := encoding.Vector(encoding.Count(1), encoding.Count(2), encoding.Count(3))

अंत में, इवेंट्स को सीधे बनाया जा सकता है:

zeekEvent := encoding.NewEvent("some_event_name", zeekVector, zeekString)

client

client, github.com/gorilla/websocket को wrap करते हुए, broker WS API से बात करने के लिए websocket glue प्रदान करता है:

इवेंट प्रकाशित करने के लिए:

broker, err := client.NewClient(...)

err := broker.PublishEvent("/the/topic", zeekEvent)

टॉपिक सब्सक्रिप्शन client.Newclient() में स्ट्रिंग्स के स्लाइस के रूप में पास किए जाते हैं। क्लाइंट की ReadEvent() विधि Broker से एक एकल इवेंट लौटाती है (किसी भी सब्सक्राइब्ड टॉपिक पर), या कोई त्रुटि जो लाइब्रेरी में ही हो सकती है या Broker से प्राप्त त्रुटि):

broker, err := client.NewClient(..., []string{"/the/topic"})

topic, zeekEvent, err := broker.ReadEvent()

यदि broker कनेक्शन को सामान्य रूप से बंद किया जाता है, तो लौटाई गई त्रुटि की जाँच करने के लिए client.IsNormalWebsocketClose() फ़ंक्शन का उपयोग किया जा सकता है।

क्लाइंट कोड को type assertions के माध्यम से इवेंट आर्गुमेंट मानों तक पहुंचना चाहिए:

if len(evt.Arguments) < someConstantGreaterOrEqualToOne {
	// handle too few arguments case
}

if evt.Arguments[0].DataType != encoding.TypeString {
	// handle unexpected data type case
}

stringArgument0, ok := evt.Arguments[0].DataValue.(string)
if !ok {
	// handle type assertion error - this would indicate a bug (we trust+verify).
}

// now we use stringArgument0

सब्सक्रिप्शन के माध्यम से प्राप्त इवेंट्स का एसिंक्रोनस हैंडलिंग और डिस्पैचिंग, Client.ReadEvent() रैपर के रूप में सबसे अच्छा लागू किया जाएगा। एक सरल कार्यान्वयन client.AsyncSubscription() में प्रदान किया गया है।

websocket कनेक्शन का अधिक उन्नत हैंडलिंग (जैसे, टाइमआउट सेट करना, पुनः-कनेक्शन को संभालना, आदि) client.Client के रैपर के रूप में सबसे अच्छा लागू किया जाता है, या एक नया/वैकल्पिक कार्यान्वयन जो encoding पैकेज का उपयोग करता है (योगदान/PRs का स्वागत है!)।

Broker TLS विवरण

Broker नेटवर्क कनेक्शन (नेटिव और websocket इंटरफ़ेस दोनों) डिफ़ॉल्ट रूप से TLS सक्षम करते हैं, एक अजीब कॉन्फ़िगरेशन के साथ जो होस्ट सत्यापन को अक्षम करता है और सिफर का एक सेट चुनता है जो प्रमाणपत्रों के बिना एन्क्रिप्शन की अनुमति देता है (Anonymous Diffie-Hellman / AECDH)। इस मोड का उपयोग करने के लिए weirdtls.BrokerDefaultTLSDialer को encoding.NewClient के dialer फ़ंक्शन तर्क के रूप में पारित करना आवश्यक है। ध्यान दें कि यह OpenSSL को निर्भरता के रूप में शामिल करता है।

वैकल्पिक रूप से, मानक लाइब्रेरी crypto/tls कार्यान्वयन का उपयोग किया जा सकता है यदि दोनों पक्षों (क्लाइंट और zeek/broker) को प्रमाणपत्रों के साथ TLS का उपयोग करने के लिए कॉन्फ़िगर किया गया है। यह लाइब्रेरी एक सुविधाजनक सहायक फ़ंक्शन (securetls.MakeSecureDialer()) प्रदान करती है जो CA और क्लाइंट प्रमाणपत्र/कुंजी के लिए PEM फ़ाइलें दिए जाने पर एक dialer फ़ंक्शन लौटाता है। इस कॉन्फ़िगरेशन के उदाहरण के लिए यह btest मामला देखें।

अंत में, redef Broker::disable_ssl = T; का उपयोग करके broker कनेक्शन के लिए TLS को बंद किया जा सकता है। एक उदाहरण के लिए यह btest मामला देखें जहां encoding.NewClient को असुरक्षित संचालन के लिए तर्कों के साथ बुलाया गया है।

zeek 7.2+ में परिवर्तन

zeek 7.2 में websocket API को broker से बाहर Cluster फ्रेमवर्क में स्थानांतरित कर दिया जाएगा, और डिफ़ॉल्ट TLS को बंद करना है। यह btest मामला नए zeek-पक्ष फ़ंक्शन का उपयोग करता है और secure तर्क को false पर सेट करके encoding.NewClient() को कॉल करके इस लाइब्रेरी का उपयोग प्रदर्शित करता है।

जब zeek 7.2 LTS रिलीज़ बन जाता है, तो इस लाइब्रेरी का एक नया (मेजर) संस्करण ऊपर वर्णित AECDH TLS मोड के लिए समर्थन हटा देगा, जिससे OpenSSL निर्भरता समाप्त हो जाएगी।

Ping/pong उदाहरण

zeek-पक्ष broker स्क्रिप्ट चलाना:

$ cd example/
$ zeek listen.zeek

अब उदाहरण चलाएँ:

$ cd example/
$ go build && ./example 
2023/05/05 12:56:55 connected to remote endpoint with UUID=c9b0bfd6-3b8d-5de2-a51c-9af7b81aaad3 version=2.5.0-dev
2023/05/05 12:56:55 > topic=/topic/test | event ping("my-message": string, "1": count)
2023/05/05 12:56:55 < topic=/topic/test | event pong("my-message": string, "2": count)
2023/05/05 12:56:56 > topic=/topic/test | event ping("my-message": string, "2": count)
2023/05/05 12:56:56 < topic=/topic/test | event pong("my-message": string, "3": count)

...इस बीच zeek स्क्रिप्ट:

peer added, [id=e537f8b4-de32-52ea-9587-4e6e15bdfe20, network=[address=127.0.0.1, bound_port=50690/tcp]]
receiver got ping: my-message, 1
receiver got ping: my-message, 2

डेव वर्कफ़्लो

encoding पैकेज में अधिकांश सहायक और बुनियादी डेटा संरचनाओं के लिए यूनिट परीक्षण हैं (go test ./... चलाएँ)।

एंड-टू-एंड परीक्षण दो btest मामलों के रूप में लागू किए गए हैं (cd tests/; btest चलाएँ)।