github.com/machinebox/remoto@v0.1.2-0.20191024144331-eff21a7d321f/README.md (about)

     1  ![Remoto banner](misc/remoto-banner-fog-by-chris-ryer.png)
     2  
     3  # Remoto
     4  
     5  Ultra-simple, fast, complete RPC ecosystem designed for right now.
     6  
     7  * Simple service definitions written in Go (interfaces and structs)
     8  * Generates servers and clients that makes implementing/consuming easy
     9  * Generates human-readable code
    10  * Supports batch requests out of the box
    11  * Lots of [templates](templates) to use today
    12  * Modify templates or write your own
    13  
    14  ## In this document
    15  
    16  * [Introduction](#introduction) - Start learning about Remoto in the introduction
    17  * [Remoto Definition Files](#remoto-definition-files) - An overview of the Remoto definition files
    18  * [Remoto command](#remoto-command) - The `remoto` command line tool
    19  * [remotohttp](#remotohttp) - Templates for Remoto powered HTTP servers and clients
    20  
    21  # Introduction
    22  
    23  Remoto is an RPC ecosystem and code generation tool. A powerful set of templates and
    24  supporting code allows you to quickly spin up RPC services, and consume them with hand crafted
    25  client libraries by experts in each particular language.
    26  
    27  ## Who is Remoto for?
    28  
    29  Remoto is for teams who want to:
    30  
    31  * Deliver mobile and web RPC services
    32  * Automate SDK and client library generation
    33  * Stick with simple and familiar technology
    34  
    35  # Remoto definition files
    36  
    37  Definition files are Go source with `.remoto.go` file extension.
    38  
    39  An example definition looks like this:
    40  
    41  ```go
    42  package project
    43  
    44  // Greeter provides greeting services.
    45  type Greeter interface {
    46  	// Greet generates a greeting.
    47  	Greet(GreetRequest) GreetResponse
    48  }
    49  
    50  // GreetRequest is the request for Greeter.GreetRequest.
    51  type GreetRequest struct {
    52  	Name string
    53  }
    54  
    55  // GreetResponse is the response for Greeter.GreetRequest.
    56  type GreetResponse struct {
    57  	Greeting string
    58  }
    59  ```
    60  
    61  * `package project` - package name can group services
    62  * `type ServiceName interface` - describes an RPC service
    63  * `Greet(GreetRequest) GreetResponse` - service method with request and response objects
    64  * `type GreetRequest struct` - describes the request data
    65  * `type GreetResponse struct` - describes the response data
    66  
    67  ## Rules
    68  
    69  * Each service is an `interface`
    70  * Each method is an endpoint
    71  * Methods must take a request object as its only argument
    72  * Methods must return the response object as the result
    73  * Only a subset of Go types are supported: `string`, `float64`, `int`, `bool`, and `struct` types
    74  * Any arrays (slices) of the supported types are also allowed (e.g. `[]string`, `[]bool`, etc.)
    75  * Comments describe the services, methods and types
    76  * Do not import packages (apart from official Remoto ones), instead your definition files should be self contained
    77  
    78  ## Special types
    79  
    80  * Learn more about specially handled types in [remototypes](remototypes).
    81  
    82  ## Tips
    83  
    84  * Avoid importing common types - describe all the required types in a single `.remoto.go` file
    85  
    86  # Remoto command
    87  
    88  The `remoto` command can be built into your development pipeline to generate source code from
    89  definition files.
    90  
    91  ```
    92  usage:
    93  	remoto sub-command
    94  ```
    95  
    96  ## Generate
    97  
    98  The generate command generates source code from a given template.
    99  
   100  ```
   101  usage:
   102  	remoto generate definition template -o output-file
   103  ```
   104  
   105  * `definition` - Path to the definition file
   106  * `template` - Path to the template to render
   107  * `output-file` - Where to save the output (folders will be created and files will be overwritten without warning)
   108  
   109  # remotohttp
   110  
   111  As well as code generation, Remoto ships with a complete HTTP client/server implementation which you can generate from your definition files.
   112  
   113  For more information, see the [remotohttp documentation](go/remotohttp).