ws

ws

تنفيذ RFC6455 WebSocket في Go.

سمات

• ترقية النسخة الصفرية
• لا توجد عمليات تخصيص وسيطة أثناء الإدخال/الإخراج
• واجهة برمجة التطبيقات منخفضة المستوى والتي تسمح ببناء المنطق الخاص بك للتعامل مع الحزم وإعادة استخدام المخازن المؤقتة
• أغلفة ومساعدات عالية المستوى حول واجهة برمجة التطبيقات (API) في حزمة wsutil ، والتي تسمح بالبدء بسرعة دون البحث في الأجزاء الداخلية للبروتوكول

التوثيق

GoDoc.

لماذا

لا تسمح تطبيقات WebSocket الحالية للمستخدمين بإعادة استخدام مخازن الإدخال/الإخراج المؤقتة بين الاتصالات بطريقة واضحة. تهدف هذه المكتبة إلى تصدير واجهة فعالة منخفضة المستوى للعمل مع البروتوكول دون فرض طريقة واحدة فقط يمكن استخدامها.

بالمناسبة، إذا كنت تريد الحصول على الأدوات ذات المستوى الأعلى، فيمكنك استخدام حزمة wsutil .

حالة

تم وضع علامة على المكتبة على أنها v1* لذا يجب ألا يتم كسر واجهة برمجة التطبيقات (API) الخاصة بها أثناء بعض التحسينات أو إعادة البناء.

يجتاز تطبيق RFC6455 هذا مجموعة اختبار Autobahn ويحظى حاليًا بتغطية تبلغ حوالي 78%.

أمثلة

يتم تطوير أمثلة التطبيقات التي تستخدم ws في أمثلة ws لمستودع منفصل.

الاستخدام

المثال ذو المستوى الأعلى لخادم صدى WebSocket:

 package main

import (
	"net/http"

	"github.com/gobwas/ws"
	"github.com/gobwas/ws/wsutil"
)

func main () {
	http . ListenAndServe ( ":8080" , http . HandlerFunc ( func ( w http. ResponseWriter , r * http. Request ) {
		conn , _ , _ , err := ws . UpgradeHTTP ( r , w )
		if err != nil {
			// handle error
		}
		go func () {
			defer conn . Close ()

			for {
				msg , op , err := wsutil . ReadClientData ( conn )
				if err != nil {
					// handle error
				}
				err = wsutil . WriteServerMessage ( conn , op , msg )
				if err != nil {
					// handle error
				}
			}
		}()
	}))
}

مثال على المستوى الأدنى، ولكن لا يزال عالي المستوى:

 import (
	"net/http"
	"io"

	"github.com/gobwas/ws"
	"github.com/gobwas/ws/wsutil"
)

func main () {
	http . ListenAndServe ( ":8080" , http . HandlerFunc ( func ( w http. ResponseWriter , r * http. Request ) {
		conn , _ , _ , err := ws . UpgradeHTTP ( r , w )
		if err != nil {
			// handle error
		}
		go func () {
			defer conn . Close ()

			var (
				state  = ws . StateServerSide
				reader = wsutil . NewReader ( conn , state )
				writer = wsutil . NewWriter ( conn , state , ws . OpText )
			)
			for {
				header , err := reader . NextFrame ()
				if err != nil {
					// handle error
				}

				// Reset writer to write frame with right operation code.
				writer . Reset ( conn , state , header . OpCode )

				if _ , err = io . Copy ( writer , reader ); err != nil {
					// handle error
				}
				if err = writer . Flush (); err != nil {
					// handle error
				}
			}
		}()
	}))
}

يمكننا تطبيق نفس النمط لقراءة وكتابة الاستجابات المنظمة من خلال برنامج تشفير وفك تشفير JSON.:

	...
	var (
		r = wsutil . NewReader ( conn , ws . StateServerSide )
		w = wsutil . NewWriter ( conn , ws . StateServerSide , ws . OpText )
		decoder = json . NewDecoder ( r )
		encoder = json . NewEncoder ( w )
	)
	for {
		hdr , err = r . NextFrame ()
		if err != nil {
			return err
		}
		if hdr . OpCode == ws . OpClose {
			return io . EOF
		}
		var req Request
		if err := decoder . Decode ( & req ); err != nil {
			return err
		}
		var resp Response
		if err := encoder . Encode ( & resp ); err != nil {
			return err
		}
		if err = w . Flush (); err != nil {
			return err
		}
	}
	...

مثال المستوى الأدنى بدون wsutil :

 package main

import (
	"net"
	"io"

	"github.com/gobwas/ws"
)

func main () {
	ln , err := net . Listen ( "tcp" , "localhost:8080" )
	if err != nil {
		log . Fatal ( err )
	}

	for {
		conn , err := ln . Accept ()
		if err != nil {
			// handle error
		}
		_ , err = ws . Upgrade ( conn )
		if err != nil {
			// handle error
		}

		go func () {
			defer conn . Close ()

			for {
				header , err := ws . ReadHeader ( conn )
				if err != nil {
					// handle error
				}

				payload := make ([] byte , header . Length )
				_ , err = io . ReadFull ( conn , payload )
				if err != nil {
					// handle error
				}
				if header . Masked {
					ws . Cipher ( payload , header . Mask , 0 )
				}

				// Reset the Masked flag, server frames must not be masked as
				// RFC6455 says.
				header . Masked = false

				if err := ws . WriteHeader ( conn , header ); err != nil {
					// handle error
				}
				if _ , err := conn . Write ( payload ); err != nil {
					// handle error
				}

				if header . OpCode == ws . OpClose {
					return
				}
			}
		}()
	}
}

ترقية النسخة الصفرية

تساعد ترقية النسخة الصفرية على تجنب عمليات التخصيص والنسخ غير الضرورية أثناء معالجة طلب ترقية HTTP.

تتم معالجة جميع الرؤوس غير المرتبطة بـ websocket باستخدام عمليات رد الاتصال الخاصة بالمستخدم المسجل والتي تكون وسيطاتها صالحة فقط حتى يتم إرجاع رد الاتصال.

المثال البسيط يبدو كالتالي:

 package main

import (
	"net"
	"log"

	"github.com/gobwas/ws"
)

func main () {
	ln , err := net . Listen ( "tcp" , "localhost:8080" )
	if err != nil {
		log . Fatal ( err )
	}
	u := ws. Upgrader {
		OnHeader : func ( key , value [] byte ) ( err error ) {
			log . Printf ( "non-websocket header: %q=%q" , key , value )
			return
		},
	}
	for {
		conn , err := ln . Accept ()
		if err != nil {
			// handle error
		}

		_ , err = u . Upgrade ( conn )
		if err != nil {
			// handle error
		}
	}
}

استخدام ws.Upgrader هنا يجلب القدرة على التحكم في الاتصالات الواردة على مستوى TCP وببساطة عدم قبولها ببعض المنطق.

ترقية النسخة الصفرية مخصصة للخدمات عالية التحميل والتي يتعين عليها التحكم في العديد من الموارد مثل المخازن المؤقتة للاتصالات.

مثال الحياة الواقعية يمكن أن يكون مثل هذا:

 package main

import (
	"fmt"
	"io"
	"log"
	"net"
	"net/http"
	"runtime"

	"github.com/gobwas/httphead"
	"github.com/gobwas/ws"
)

func main () {
	ln , err := net . Listen ( "tcp" , "localhost:8080" )
	if err != nil {
		// handle error
	}

	// Prepare handshake header writer from http.Header mapping.
	header := ws . HandshakeHeaderHTTP (http. Header {
		"X-Go-Version" : [] string { runtime . Version ()},
	})

	u := ws. Upgrader {
		OnHost : func ( host [] byte ) error {
			if string ( host ) == "github.com" {
				return nil
			}
			return ws . RejectConnectionError (
				ws . RejectionStatus ( 403 ),
				ws . RejectionHeader ( ws . HandshakeHeaderString (
					"X-Want-Host: github.com r n " ,
				)),
			)
		},
		OnHeader : func ( key , value [] byte ) error {
			if string ( key ) != "Cookie" {
				return nil
			}
			ok := httphead . ScanCookie ( value , func ( key , value [] byte ) bool {
				// Check session here or do some other stuff with cookies.
				// Maybe copy some values for future use.
				return true
			})
			if ok {
				return nil
			}
			return ws . RejectConnectionError (
				ws . RejectionReason ( "bad cookie" ),
				ws . RejectionStatus ( 400 ),
			)
		},
		OnBeforeUpgrade : func () (ws. HandshakeHeader , error ) {
			return header , nil
		},
	}
	for {
		conn , err := ln . Accept ()
		if err != nil {
			log . Fatal ( err )
		}
		_ , err = u . Upgrade ( conn )
		if err != nil {
			log . Printf ( "upgrade error: %s" , err )
		}
	}
}

ضغط

توجد حزمة ws/wsflate لدعم ملحق ضغط Permessage-Deflate.

إنه يوفر أغلفة إدخال/إخراج بسيطة لاستخدامها مع أي تطبيق مفرغ (على سبيل المثال، الضغط/التفريغ الخاص بالمكتبة القياسية).

وهو متوافق أيضًا مع قارئ وكاتب wsutil من خلال توفير نوع wsflate.MessageState ، الذي ينفذ واجهات wsutil.SendExtension و wsutil.RecvExtension .

 package main

import (
	"bytes"
	"log"
	"net"

	"github.com/gobwas/ws"
	"github.com/gobwas/ws/wsflate"
)

func main () {
	ln , err := net . Listen ( "tcp" , "localhost:8080" )
	if err != nil {
		// handle error
	}
	e := wsflate. Extension {
		// We are using default parameters here since we use
		// wsflate.{Compress,Decompress}Frame helpers below in the code.
		// This assumes that we use standard compress/flate package as flate
		// implementation.
		Parameters : wsflate . DefaultParameters ,
	}
	u := ws. Upgrader {
		Negotiate : e . Negotiate ,
	}
	for {
		conn , err := ln . Accept ()
		if err != nil {
			log . Fatal ( err )
		}

		// Reset extension after previous upgrades.
		e . Reset ()

		_ , err = u . Upgrade ( conn )
		if err != nil {
			log . Printf ( "upgrade error: %s" , err )
			continue
		}
		if _ , ok := e . Accepted (); ! ok {
			log . Printf ( "didn't negotiate compression for %s" , conn . RemoteAddr ())
			conn . Close ()
			continue
		}

		go func () {
			defer conn . Close ()
			for {
				frame , err := ws . ReadFrame ( conn )
				if err != nil {
					// Handle error.
					return
				}

				frame = ws . UnmaskFrameInPlace ( frame )

				if wsflate . IsCompressed ( frame . Header ) {
					// Note that even after successful negotiation of
					// compression extension, both sides are able to send
					// non-compressed messages.
					frame , err = wsflate . DecompressFrame ( frame )
					if err != nil {
						// Handle error.
						return
					}
				}

				// Do something with frame...

				ack := ws . NewTextFrame ([] byte ( "this is an acknowledgement" ))

				// Compress response unconditionally.
				ack , err = wsflate . CompressFrame ( ack )
				if err != nil {
					// Handle error.
					return
				}
				if err = ws . WriteFrame ( conn , ack ); err != nil {
					// Handle error.
					return
				}
			}
		}()
	}
}

يمكنك استخدام الضغط مع حزمة wsutil بهذه الطريقة:

	// Upgrade somehow and negotiate compression to get the conn...

	// Initialize flate reader. We are using nil as a source io.Reader because
	// we will Reset() it in the message i/o loop below.
	fr := wsflate . NewReader ( nil , func ( r io. Reader ) wsflate. Decompressor {
		return flate . NewReader ( r )
	})
	// Initialize flate writer. We are using nil as a destination io.Writer
	// because we will Reset() it in the message i/o loop below.
	fw := wsflate . NewWriter ( nil , func ( w io. Writer ) wsflate. Compressor {
		f , _ := flate . NewWriter ( w , 9 )
		return f
	})

	// Declare compression message state variable.
	//
	// It has two goals:
	// - Allow users to check whether received message is compressed or not.
	// - Help wsutil.Reader and wsutil.Writer to set/unset appropriate
	//   WebSocket header bits while writing next frame to the wire (it
	//   implements wsutil.RecvExtension and wsutil.SendExtension).
	var msg wsflate. MessageState

	// Initialize WebSocket reader as previously. 
	// Please note the use of Reader.Extensions field as well as
	// of ws.StateExtended flag.
	rd := & wsutil. Reader {
		Source :     conn ,
		State :      ws . StateServerSide | ws . StateExtended ,
		Extensions : []wsutil. RecvExtension {
			& msg , 
		},
	}

	// Initialize WebSocket writer with ws.StateExtended flag as well.
	wr := wsutil . NewWriter ( conn , ws . StateServerSide | ws . StateExtended , 0 )
	// Use the message state as wsutil.SendExtension.
	wr . SetExtensions ( & msg )

	for {
		h , err := rd . NextFrame ()
		if err != nil {
			// handle error.
		}
		if h . OpCode . IsControl () {
			// handle control frame.
		}
		if ! msg . IsCompressed () {
			// handle uncompressed frame (skipped for the sake of example
			// simplicity).
		}

		// Reset the writer to echo same op code.
		wr . Reset ( h . OpCode )

		// Reset both flate reader and writer to start the new round of i/o.
		fr . Reset ( rd )
		fw . Reset ( wr )

		// Copy whole message from reader to writer decompressing it and
		// compressing again.
		if _ , err := io . Copy ( fw , fr ); err != nil {
			// handle error.
		}
		// Flush any remaining buffers from flate writer to WebSocket writer.
		if err := fw . Close (); err != nil {
			// handle error.
		}
		// Flush the whole WebSocket message to the wire.
		if err := wr . Flush (); err != nil {
			// handle error.
		}
	}