Source file src/net/rpc/server.go

Documentation: net/rpc

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  	Package rpc provides access to the exported methods of an object across a
     7  	network or other I/O connection.  A server registers an object, making it visible
     8  	as a service with the name of the type of the object.  After registration, exported
     9  	methods of the object will be accessible remotely.  A server may register multiple
    10  	objects (services) of different types but it is an error to register multiple
    11  	objects of the same type.
    12  
    13  	Only methods that satisfy these criteria will be made available for remote access;
    14  	other methods will be ignored:
    15  
    16  		- the method's type is exported.
    17  		- the method is exported.
    18  		- the method has two arguments, both exported (or builtin) types.
    19  		- the method's second argument is a pointer.
    20  		- the method has return type error.
    21  
    22  	In effect, the method must look schematically like
    23  
    24  		func (t *T) MethodName(argType T1, replyType *T2) error
    25  
    26  	where T1 and T2 can be marshaled by encoding/gob.
    27  	These requirements apply even if a different codec is used.
    28  	(In the future, these requirements may soften for custom codecs.)
    29  
    30  	The method's first argument represents the arguments provided by the caller; the
    31  	second argument represents the result parameters to be returned to the caller.
    32  	The method's return value, if non-nil, is passed back as a string that the client
    33  	sees as if created by errors.New.  If an error is returned, the reply parameter
    34  	will not be sent back to the client.
    35  
    36  	The server may handle requests on a single connection by calling ServeConn.  More
    37  	typically it will create a network listener and call Accept or, for an HTTP
    38  	listener, HandleHTTP and http.Serve.
    39  
    40  	A client wishing to use the service establishes a connection and then invokes
    41  	NewClient on the connection.  The convenience function Dial (DialHTTP) performs
    42  	both steps for a raw network connection (an HTTP connection).  The resulting
    43  	Client object has two methods, Call and Go, that specify the service and method to
    44  	call, a pointer containing the arguments, and a pointer to receive the result
    45  	parameters.
    46  
    47  	The Call method waits for the remote call to complete while the Go method
    48  	launches the call asynchronously and signals completion using the Call
    49  	structure's Done channel.
    50  
    51  	Unless an explicit codec is set up, package encoding/gob is used to
    52  	transport the data.
    53  
    54  	Here is a simple example.  A server wishes to export an object of type Arith:
    55  
    56  		package server
    57  
    58  		import "errors"
    59  
    60  		type Args struct {
    61  			A, B int
    62  		}
    63  
    64  		type Quotient struct {
    65  			Quo, Rem int
    66  		}
    67  
    68  		type Arith int
    69  
    70  		func (t *Arith) Multiply(args *Args, reply *int) error {
    71  			*reply = args.A * args.B
    72  			return nil
    73  		}
    74  
    75  		func (t *Arith) Divide(args *Args, quo *Quotient) error {
    76  			if args.B == 0 {
    77  				return errors.New("divide by zero")
    78  			}
    79  			quo.Quo = args.A / args.B
    80  			quo.Rem = args.A % args.B
    81  			return nil
    82  		}
    83  
    84  	The server calls (for HTTP service):
    85  
    86  		arith := new(Arith)
    87  		rpc.Register(arith)
    88  		rpc.HandleHTTP()
    89  		l, e := net.Listen("tcp", ":1234")
    90  		if e != nil {
    91  			log.Fatal("listen error:", e)
    92  		}
    93  		go http.Serve(l, nil)
    94  
    95  	At this point, clients can see a service "Arith" with methods "Arith.Multiply" and
    96  	"Arith.Divide".  To invoke one, a client first dials the server:
    97  
    98  		client, err := rpc.DialHTTP("tcp", serverAddress + ":1234")
    99  		if err != nil {
   100  			log.Fatal("dialing:", err)
   101  		}
   102  
   103  	Then it can make a remote call:
   104  
   105  		// Synchronous call
   106  		args := &server.Args{7,8}
   107  		var reply int
   108  		err = client.Call("Arith.Multiply", args, &reply)
   109  		if err != nil {
   110  			log.Fatal("arith error:", err)
   111  		}
   112  		fmt.Printf("Arith: %d*%d=%d", args.A, args.B, reply)
   113  
   114  	or
   115  
   116  		// Asynchronous call
   117  		quotient := new(Quotient)
   118  		divCall := client.Go("Arith.Divide", args, quotient, nil)
   119  		replyCall := <-divCall.Done	// will be equal to divCall
   120  		// check errors, print, etc.
   121  
   122  	A server implementation will often provide a simple, type-safe wrapper for the
   123  	client.
   124  
   125  	The net/rpc package is frozen and is not accepting new features.
   126  */
   127  package rpc
   128  
   129  import (
   130  	"bufio"
   131  	"encoding/gob"
   132  	"errors"
   133  	"go/token"
   134  	"io"
   135  	"log"
   136  	"net"
   137  	"net/http"
   138  	"reflect"
   139  	"strings"
   140  	"sync"
   141  )
   142  
   143  const (
   144  	// Defaults used by HandleHTTP
   145  	DefaultRPCPath   = "/_goRPC_"
   146  	DefaultDebugPath = "/debug/rpc"
   147  )
   148  
   149  // Precompute the reflect type for error. Can't use error directly
   150  // because Typeof takes an empty interface value. This is annoying.
   151  var typeOfError = reflect.TypeOf((*error)(nil)).Elem()
   152  
   153  type methodType struct {
   154  	sync.Mutex // protects counters
   155  	method     reflect.Method
   156  	ArgType    reflect.Type
   157  	ReplyType  reflect.Type
   158  	numCalls   uint
   159  }
   160  
   161  type service struct {
   162  	name   string                 // name of service
   163  	rcvr   reflect.Value          // receiver of methods for the service
   164  	typ    reflect.Type           // type of the receiver
   165  	method map[string]*methodType // registered methods
   166  }
   167  
   168  // Request is a header written before every RPC call. It is used internally
   169  // but documented here as an aid to debugging, such as when analyzing
   170  // network traffic.
   171  type Request struct {
   172  	ServiceMethod string   // format: "Service.Method"
   173  	Seq           uint64   // sequence number chosen by client
   174  	next          *Request // for free list in Server
   175  }
   176  
   177  // Response is a header written before every RPC return. It is used internally
   178  // but documented here as an aid to debugging, such as when analyzing
   179  // network traffic.
   180  type Response struct {
   181  	ServiceMethod string    // echoes that of the Request
   182  	Seq           uint64    // echoes that of the request
   183  	Error         string    // error, if any.
   184  	next          *Response // for free list in Server
   185  }
   186  
   187  // Server represents an RPC Server.
   188  type Server struct {
   189  	serviceMap sync.Map   // map[string]*service
   190  	reqLock    sync.Mutex // protects freeReq
   191  	freeReq    *Request
   192  	respLock   sync.Mutex // protects freeResp
   193  	freeResp   *Response
   194  }
   195  
   196  // NewServer returns a new Server.
   197  func NewServer() *Server {
   198  	return &Server{}
   199  }
   200  
   201  // DefaultServer is the default instance of *Server.
   202  var DefaultServer = NewServer()
   203  
   204  // Is this type exported or a builtin?
   205  func isExportedOrBuiltinType(t reflect.Type) bool {
   206  	for t.Kind() == reflect.Ptr {
   207  		t = t.Elem()
   208  	}
   209  	// PkgPath will be non-empty even for an exported type,
   210  	// so we need to check the type name as well.
   211  	return token.IsExported(t.Name()) || t.PkgPath() == ""
   212  }
   213  
   214  // Register publishes in the server the set of methods of the
   215  // receiver value that satisfy the following conditions:
   216  //	- exported method of exported type
   217  //	- two arguments, both of exported type
   218  //	- the second argument is a pointer
   219  //	- one return value, of type error
   220  // It returns an error if the receiver is not an exported type or has
   221  // no suitable methods. It also logs the error using package log.
   222  // The client accesses each method using a string of the form "Type.Method",
   223  // where Type is the receiver's concrete type.
   224  func (server *Server) Register(rcvr interface{}) error {
   225  	return server.register(rcvr, "", false)
   226  }
   227  
   228  // RegisterName is like Register but uses the provided name for the type
   229  // instead of the receiver's concrete type.
   230  func (server *Server) RegisterName(name string, rcvr interface{}) error {
   231  	return server.register(rcvr, name, true)
   232  }
   233  
   234  func (server *Server) register(rcvr interface{}, name string, useName bool) error {
   235  	s := new(service)
   236  	s.typ = reflect.TypeOf(rcvr)
   237  	s.rcvr = reflect.ValueOf(rcvr)
   238  	sname := reflect.Indirect(s.rcvr).Type().Name()
   239  	if useName {
   240  		sname = name
   241  	}
   242  	if sname == "" {
   243  		s := "rpc.Register: no service name for type " + s.typ.String()
   244  		log.Print(s)
   245  		return errors.New(s)
   246  	}
   247  	if !token.IsExported(sname) && !useName {
   248  		s := "rpc.Register: type " + sname + " is not exported"
   249  		log.Print(s)
   250  		return errors.New(s)
   251  	}
   252  	s.name = sname
   253  
   254  	// Install the methods
   255  	s.method = suitableMethods(s.typ, true)
   256  
   257  	if len(s.method) == 0 {
   258  		str := ""
   259  
   260  		// To help the user, see if a pointer receiver would work.
   261  		method := suitableMethods(reflect.PtrTo(s.typ), false)
   262  		if len(method) != 0 {
   263  			str = "rpc.Register: type " + sname + " has no exported methods of suitable type (hint: pass a pointer to value of that type)"
   264  		} else {
   265  			str = "rpc.Register: type " + sname + " has no exported methods of suitable type"
   266  		}
   267  		log.Print(str)
   268  		return errors.New(str)
   269  	}
   270  
   271  	if _, dup := server.serviceMap.LoadOrStore(sname, s); dup {
   272  		return errors.New("rpc: service already defined: " + sname)
   273  	}
   274  	return nil
   275  }
   276  
   277  // suitableMethods returns suitable Rpc methods of typ, it will report
   278  // error using log if reportErr is true.
   279  func suitableMethods(typ reflect.Type, reportErr bool) map[string]*methodType {
   280  	methods := make(map[string]*methodType)
   281  	for m := 0; m < typ.NumMethod(); m++ {
   282  		method := typ.Method(m)
   283  		mtype := method.Type
   284  		mname := method.Name
   285  		// Method must be exported.
   286  		if method.PkgPath != "" {
   287  			continue
   288  		}
   289  		// Method needs three ins: receiver, *args, *reply.
   290  		if mtype.NumIn() != 3 {
   291  			if reportErr {
   292  				log.Printf("rpc.Register: method %q has %d input parameters; needs exactly three\n", mname, mtype.NumIn())
   293  			}
   294  			continue
   295  		}
   296  		// First arg need not be a pointer.
   297  		argType := mtype.In(1)
   298  		if !isExportedOrBuiltinType(argType) {
   299  			if reportErr {
   300  				log.Printf("rpc.Register: argument type of method %q is not exported: %q\n", mname, argType)
   301  			}
   302  			continue
   303  		}
   304  		// Second arg must be a pointer.
   305  		replyType := mtype.In(2)
   306  		if replyType.Kind() != reflect.Ptr {
   307  			if reportErr {
   308  				log.Printf("rpc.Register: reply type of method %q is not a pointer: %q\n", mname, replyType)
   309  			}
   310  			continue
   311  		}
   312  		// Reply type must be exported.
   313  		if !isExportedOrBuiltinType(replyType) {
   314  			if reportErr {
   315  				log.Printf("rpc.Register: reply type of method %q is not exported: %q\n", mname, replyType)
   316  			}
   317  			continue
   318  		}
   319  		// Method needs one out.
   320  		if mtype.NumOut() != 1 {
   321  			if reportErr {
   322  				log.Printf("rpc.Register: method %q has %d output parameters; needs exactly one\n", mname, mtype.NumOut())
   323  			}
   324  			continue
   325  		}
   326  		// The return type of the method must be error.
   327  		if returnType := mtype.Out(0); returnType != typeOfError {
   328  			if reportErr {
   329  				log.Printf("rpc.Register: return type of method %q is %q, must be error\n", mname, returnType)
   330  			}
   331  			continue
   332  		}
   333  		methods[mname] = &methodType{method: method, ArgType: argType, ReplyType: replyType}
   334  	}
   335  	return methods
   336  }
   337  
   338  // A value sent as a placeholder for the server's response value when the server
   339  // receives an invalid request. It is never decoded by the client since the Response
   340  // contains an error when it is used.
   341  var invalidRequest = struct{}{}
   342  
   343  func (server *Server) sendResponse(sending *sync.Mutex, req *Request, reply interface{}, codec ServerCodec, errmsg string) {
   344  	resp := server.getResponse()
   345  	// Encode the response header
   346  	resp.ServiceMethod = req.ServiceMethod
   347  	if errmsg != "" {
   348  		resp.Error = errmsg
   349  		reply = invalidRequest
   350  	}
   351  	resp.Seq = req.Seq
   352  	sending.Lock()
   353  	err := codec.WriteResponse(resp, reply)
   354  	if debugLog && err != nil {
   355  		log.Println("rpc: writing response:", err)
   356  	}
   357  	sending.Unlock()
   358  	server.freeResponse(resp)
   359  }
   360  
   361  func (m *methodType) NumCalls() (n uint) {
   362  	m.Lock()
   363  	n = m.numCalls
   364  	m.Unlock()
   365  	return n
   366  }
   367  
   368  func (s *service) call(server *Server, sending *sync.Mutex, wg *sync.WaitGroup, mtype *methodType, req *Request, argv, replyv reflect.Value, codec ServerCodec) {
   369  	if wg != nil {
   370  		defer wg.Done()
   371  	}
   372  	mtype.Lock()
   373  	mtype.numCalls++
   374  	mtype.Unlock()
   375  	function := mtype.method.Func
   376  	// Invoke the method, providing a new value for the reply.
   377  	returnValues := function.Call([]reflect.Value{s.rcvr, argv, replyv})
   378  	// The return value for the method is an error.
   379  	errInter := returnValues[0].Interface()
   380  	errmsg := ""
   381  	if errInter != nil {
   382  		errmsg = errInter.(error).Error()
   383  	}
   384  	server.sendResponse(sending, req, replyv.Interface(), codec, errmsg)
   385  	server.freeRequest(req)
   386  }
   387  
   388  type gobServerCodec struct {
   389  	rwc    io.ReadWriteCloser
   390  	dec    *gob.Decoder
   391  	enc    *gob.Encoder
   392  	encBuf *bufio.Writer
   393  	closed bool
   394  }
   395  
   396  func (c *gobServerCodec) ReadRequestHeader(r *Request) error {
   397  	return c.dec.Decode(r)
   398  }
   399  
   400  func (c *gobServerCodec) ReadRequestBody(body interface{}) error {
   401  	return c.dec.Decode(body)
   402  }
   403  
   404  func (c *gobServerCodec) WriteResponse(r *Response, body interface{}) (err error) {
   405  	if err = c.enc.Encode(r); err != nil {
   406  		if c.encBuf.Flush() == nil {
   407  			// Gob couldn't encode the header. Should not happen, so if it does,
   408  			// shut down the connection to signal that the connection is broken.
   409  			log.Println("rpc: gob error encoding response:", err)
   410  			c.Close()
   411  		}
   412  		return
   413  	}
   414  	if err = c.enc.Encode(body); err != nil {
   415  		if c.encBuf.Flush() == nil {
   416  			// Was a gob problem encoding the body but the header has been written.
   417  			// Shut down the connection to signal that the connection is broken.
   418  			log.Println("rpc: gob error encoding body:", err)
   419  			c.Close()
   420  		}
   421  		return
   422  	}
   423  	return c.encBuf.Flush()
   424  }
   425  
   426  func (c *gobServerCodec) Close() error {
   427  	if c.closed {
   428  		// Only call c.rwc.Close once; otherwise the semantics are undefined.
   429  		return nil
   430  	}
   431  	c.closed = true
   432  	return c.rwc.Close()
   433  }
   434  
   435  // ServeConn runs the server on a single connection.
   436  // ServeConn blocks, serving the connection until the client hangs up.
   437  // The caller typically invokes ServeConn in a go statement.
   438  // ServeConn uses the gob wire format (see package gob) on the
   439  // connection. To use an alternate codec, use ServeCodec.
   440  // See NewClient's comment for information about concurrent access.
   441  func (server *Server) ServeConn(conn io.ReadWriteCloser) {
   442  	buf := bufio.NewWriter(conn)
   443  	srv := &gobServerCodec{
   444  		rwc:    conn,
   445  		dec:    gob.NewDecoder(conn),
   446  		enc:    gob.NewEncoder(buf),
   447  		encBuf: buf,
   448  	}
   449  	server.ServeCodec(srv)
   450  }
   451  
   452  // ServeCodec is like ServeConn but uses the specified codec to
   453  // decode requests and encode responses.
   454  func (server *Server) ServeCodec(codec ServerCodec) {
   455  	sending := new(sync.Mutex)
   456  	wg := new(sync.WaitGroup)
   457  	for {
   458  		service, mtype, req, argv, replyv, keepReading, err := server.readRequest(codec)
   459  		if err != nil {
   460  			if debugLog && err != io.EOF {
   461  				log.Println("rpc:", err)
   462  			}
   463  			if !keepReading {
   464  				break
   465  			}
   466  			// send a response if we actually managed to read a header.
   467  			if req != nil {
   468  				server.sendResponse(sending, req, invalidRequest, codec, err.Error())
   469  				server.freeRequest(req)
   470  			}
   471  			continue
   472  		}
   473  		wg.Add(1)
   474  		go service.call(server, sending, wg, mtype, req, argv, replyv, codec)
   475  	}
   476  	// We've seen that there are no more requests.
   477  	// Wait for responses to be sent before closing codec.
   478  	wg.Wait()
   479  	codec.Close()
   480  }
   481  
   482  // ServeRequest is like ServeCodec but synchronously serves a single request.
   483  // It does not close the codec upon completion.
   484  func (server *Server) ServeRequest(codec ServerCodec) error {
   485  	sending := new(sync.Mutex)
   486  	service, mtype, req, argv, replyv, keepReading, err := server.readRequest(codec)
   487  	if err != nil {
   488  		if !keepReading {
   489  			return err
   490  		}
   491  		// send a response if we actually managed to read a header.
   492  		if req != nil {
   493  			server.sendResponse(sending, req, invalidRequest, codec, err.Error())
   494  			server.freeRequest(req)
   495  		}
   496  		return err
   497  	}
   498  	service.call(server, sending, nil, mtype, req, argv, replyv, codec)
   499  	return nil
   500  }
   501  
   502  func (server *Server) getRequest() *Request {
   503  	server.reqLock.Lock()
   504  	req := server.freeReq
   505  	if req == nil {
   506  		req = new(Request)
   507  	} else {
   508  		server.freeReq = req.next
   509  		*req = Request{}
   510  	}
   511  	server.reqLock.Unlock()
   512  	return req
   513  }
   514  
   515  func (server *Server) freeRequest(req *Request) {
   516  	server.reqLock.Lock()
   517  	req.next = server.freeReq
   518  	server.freeReq = req
   519  	server.reqLock.Unlock()
   520  }
   521  
   522  func (server *Server) getResponse() *Response {
   523  	server.respLock.Lock()
   524  	resp := server.freeResp
   525  	if resp == nil {
   526  		resp = new(Response)
   527  	} else {
   528  		server.freeResp = resp.next
   529  		*resp = Response{}
   530  	}
   531  	server.respLock.Unlock()
   532  	return resp
   533  }
   534  
   535  func (server *Server) freeResponse(resp *Response) {
   536  	server.respLock.Lock()
   537  	resp.next = server.freeResp
   538  	server.freeResp = resp
   539  	server.respLock.Unlock()
   540  }
   541  
   542  func (server *Server) readRequest(codec ServerCodec) (service *service, mtype *methodType, req *Request, argv, replyv reflect.Value, keepReading bool, err error) {
   543  	service, mtype, req, keepReading, err = server.readRequestHeader(codec)
   544  	if err != nil {
   545  		if !keepReading {
   546  			return
   547  		}
   548  		// discard body
   549  		codec.ReadRequestBody(nil)
   550  		return
   551  	}
   552  
   553  	// Decode the argument value.
   554  	argIsValue := false // if true, need to indirect before calling.
   555  	if mtype.ArgType.Kind() == reflect.Ptr {
   556  		argv = reflect.New(mtype.ArgType.Elem())
   557  	} else {
   558  		argv = reflect.New(mtype.ArgType)
   559  		argIsValue = true
   560  	}
   561  	// argv guaranteed to be a pointer now.
   562  	if err = codec.ReadRequestBody(argv.Interface()); err != nil {
   563  		return
   564  	}
   565  	if argIsValue {
   566  		argv = argv.Elem()
   567  	}
   568  
   569  	replyv = reflect.New(mtype.ReplyType.Elem())
   570  
   571  	switch mtype.ReplyType.Elem().Kind() {
   572  	case reflect.Map:
   573  		replyv.Elem().Set(reflect.MakeMap(mtype.ReplyType.Elem()))
   574  	case reflect.Slice:
   575  		replyv.Elem().Set(reflect.MakeSlice(mtype.ReplyType.Elem(), 0, 0))
   576  	}
   577  	return
   578  }
   579  
   580  func (server *Server) readRequestHeader(codec ServerCodec) (svc *service, mtype *methodType, req *Request, keepReading bool, err error) {
   581  	// Grab the request header.
   582  	req = server.getRequest()
   583  	err = codec.ReadRequestHeader(req)
   584  	if err != nil {
   585  		req = nil
   586  		if err == io.EOF || err == io.ErrUnexpectedEOF {
   587  			return
   588  		}
   589  		err = errors.New("rpc: server cannot decode request: " + err.Error())
   590  		return
   591  	}
   592  
   593  	// We read the header successfully. If we see an error now,
   594  	// we can still recover and move on to the next request.
   595  	keepReading = true
   596  
   597  	dot := strings.LastIndex(req.ServiceMethod, ".")
   598  	if dot < 0 {
   599  		err = errors.New("rpc: service/method request ill-formed: " + req.ServiceMethod)
   600  		return
   601  	}
   602  	serviceName := req.ServiceMethod[:dot]
   603  	methodName := req.ServiceMethod[dot+1:]
   604  
   605  	// Look up the request.
   606  	svci, ok := server.serviceMap.Load(serviceName)
   607  	if !ok {
   608  		err = errors.New("rpc: can't find service " + req.ServiceMethod)
   609  		return
   610  	}
   611  	svc = svci.(*service)
   612  	mtype = svc.method[methodName]
   613  	if mtype == nil {
   614  		err = errors.New("rpc: can't find method " + req.ServiceMethod)
   615  	}
   616  	return
   617  }
   618  
   619  // Accept accepts connections on the listener and serves requests
   620  // for each incoming connection. Accept blocks until the listener
   621  // returns a non-nil error. The caller typically invokes Accept in a
   622  // go statement.
   623  func (server *Server) Accept(lis net.Listener) {
   624  	for {
   625  		conn, err := lis.Accept()
   626  		if err != nil {
   627  			log.Print("rpc.Serve: accept:", err.Error())
   628  			return
   629  		}
   630  		go server.ServeConn(conn)
   631  	}
   632  }
   633  
   634  // Register publishes the receiver's methods in the DefaultServer.
   635  func Register(rcvr interface{}) error { return DefaultServer.Register(rcvr) }
   636  
   637  // RegisterName is like Register but uses the provided name for the type
   638  // instead of the receiver's concrete type.
   639  func RegisterName(name string, rcvr interface{}) error {
   640  	return DefaultServer.RegisterName(name, rcvr)
   641  }
   642  
   643  // A ServerCodec implements reading of RPC requests and writing of
   644  // RPC responses for the server side of an RPC session.
   645  // The server calls ReadRequestHeader and ReadRequestBody in pairs
   646  // to read requests from the connection, and it calls WriteResponse to
   647  // write a response back. The server calls Close when finished with the
   648  // connection. ReadRequestBody may be called with a nil
   649  // argument to force the body of the request to be read and discarded.
   650  // See NewClient's comment for information about concurrent access.
   651  type ServerCodec interface {
   652  	ReadRequestHeader(*Request) error
   653  	ReadRequestBody(interface{}) error
   654  	WriteResponse(*Response, interface{}) error
   655  
   656  	// Close can be called multiple times and must be idempotent.
   657  	Close() error
   658  }
   659  
   660  // ServeConn runs the DefaultServer on a single connection.
   661  // ServeConn blocks, serving the connection until the client hangs up.
   662  // The caller typically invokes ServeConn in a go statement.
   663  // ServeConn uses the gob wire format (see package gob) on the
   664  // connection. To use an alternate codec, use ServeCodec.
   665  // See NewClient's comment for information about concurrent access.
   666  func ServeConn(conn io.ReadWriteCloser) {
   667  	DefaultServer.ServeConn(conn)
   668  }
   669  
   670  // ServeCodec is like ServeConn but uses the specified codec to
   671  // decode requests and encode responses.
   672  func ServeCodec(codec ServerCodec) {
   673  	DefaultServer.ServeCodec(codec)
   674  }
   675  
   676  // ServeRequest is like ServeCodec but synchronously serves a single request.
   677  // It does not close the codec upon completion.
   678  func ServeRequest(codec ServerCodec) error {
   679  	return DefaultServer.ServeRequest(codec)
   680  }
   681  
   682  // Accept accepts connections on the listener and serves requests
   683  // to DefaultServer for each incoming connection.
   684  // Accept blocks; the caller typically invokes it in a go statement.
   685  func Accept(lis net.Listener) { DefaultServer.Accept(lis) }
   686  
   687  // Can connect to RPC service using HTTP CONNECT to rpcPath.
   688  var connected = "200 Connected to Go RPC"
   689  
   690  // ServeHTTP implements an http.Handler that answers RPC requests.
   691  func (server *Server) ServeHTTP(w http.ResponseWriter, req *http.Request) {
   692  	if req.Method != "CONNECT" {
   693  		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
   694  		w.WriteHeader(http.StatusMethodNotAllowed)
   695  		io.WriteString(w, "405 must CONNECT\n")
   696  		return
   697  	}
   698  	conn, _, err := w.(http.Hijacker).Hijack()
   699  	if err != nil {
   700  		log.Print("rpc hijacking ", req.RemoteAddr, ": ", err.Error())
   701  		return
   702  	}
   703  	io.WriteString(conn, "HTTP/1.0 "+connected+"\n\n")
   704  	server.ServeConn(conn)
   705  }
   706  
   707  // HandleHTTP registers an HTTP handler for RPC messages on rpcPath,
   708  // and a debugging handler on debugPath.
   709  // It is still necessary to invoke http.Serve(), typically in a go statement.
   710  func (server *Server) HandleHTTP(rpcPath, debugPath string) {
   711  	http.Handle(rpcPath, server)
   712  	http.Handle(debugPath, debugHTTP{server})
   713  }
   714  
   715  // HandleHTTP registers an HTTP handler for RPC messages to DefaultServer
   716  // on DefaultRPCPath and a debugging handler on DefaultDebugPath.
   717  // It is still necessary to invoke http.Serve(), typically in a go statement.
   718  func HandleHTTP() {
   719  	DefaultServer.HandleHTTP(DefaultRPCPath, DefaultDebugPath)
   720  }
   721  

View as plain text