storj.io/minio@v0.0.0-20230509071714-0cbc90f649b1/pkg/rpc/doc.go (about)

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Copyright 2012 The Gorilla Authors. All rights reserved.
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  
     6  // Copyright 2020 MinIO, Inc. All rights reserved.
     7  // forked from https://github.com/gorilla/rpc/v2
     8  // modified to be used with MinIO under Apache
     9  // 2.0 license that can be found in the LICENSE file.
    10  
    11  /*
    12  Package gorilla/rpc is a foundation for RPC over HTTP services, providing
    13  access to the exported methods of an object through HTTP requests.
    14  
    15  This package derives from the standard net/rpc package but uses a single HTTP
    16  request per call instead of persistent connections. Other differences
    17  compared to net/rpc:
    18  
    19  	- Multiple codecs can be registered in the same server.
    20  	- A codec is chosen based on the "Content-Type" header from the request.
    21  	- Service methods also receive http.Request as parameter.
    22  	- This package can be used on Google App Engine.
    23  
    24  Let's setup a server and register a codec and service:
    25  
    26  	import (
    27  		"http"
    28  		"github.com/minio/minio/pkg/rpc/"
    29  		"github.com/minio/minio/pkg/rpc/json2"
    30  	)
    31  
    32  	func init() {
    33  		s := rpc.NewServer()
    34  		s.RegisterCodec(json2.NewCodec(), "application/json")
    35  		s.RegisterService(new(HelloService), "")
    36  		http.Handle("/rpc", s)
    37  	}
    38  
    39  This server handles requests to the "/rpc" path using a JSON codec.
    40  A codec is tied to a content type. In the example above, the JSON codec is
    41  registered to serve requests with "application/json" as the value for the
    42  "Content-Type" header. If the header includes a charset definition, it is
    43  ignored; only the media-type part is taken into account.
    44  
    45  A service can be registered using a name. If the name is empty, like in the
    46  example above, it will be inferred from the service type.
    47  
    48  That's all about the server setup. Now let's define a simple service:
    49  
    50  	type HelloArgs struct {
    51  		Who string
    52  	}
    53  
    54  	type HelloReply struct {
    55  		Message string
    56  	}
    57  
    58  	type HelloService struct {}
    59  
    60  	func (h *HelloService) Say(r *http.Request, args *HelloArgs, reply *HelloReply) error {
    61  		reply.Message = "Hello, " + args.Who + "!"
    62  		return nil
    63  	}
    64  
    65  The example above defines a service with a method "HelloService.Say" and
    66  the arguments and reply related to that method.
    67  
    68  The service must be exported (begin with an upper case letter) or local
    69  (defined in the package registering the service).
    70  
    71  When a service is registered, the server inspects the service methods
    72  and make available the ones that follow these rules:
    73  
    74  	- The method name is exported.
    75  	- The method has three arguments: *http.Request, *args, *reply.
    76  	- All three arguments are pointers.
    77  	- The second and third arguments are exported or local.
    78  	- The method has return type error.
    79  
    80  All other methods are ignored.
    81  */
    82  package rpc