Defining a Service

Defining A Service #

Furo services are organized in packages. They can use all types that you have defined in your project or are installed as dependencies.

Lets do a simple example in µSpec and spec and see what the resulting proto will be.

Define the service in µSpec #

The following example is a complete service definition. You can use every type from your specs and installed dependencies. You do not need to import them. The imports are resolved and checked by Furo when you translate your µSecs to standard specs with the command furo muSpec2spec.

File: muspec/auth/auth.services.yaml

1
2
3
4
5
6
7
8

- name: AuthSession
  description: Login with credentials. The service should set a auth cookie on successful login and delete it on logout
  package: auth
  target: authservice.proto
  services:
    - md: 'Create: POST /auth auth.Credentials , google.protobuf.Empty #Login with credentials #A login is nothing else then creating a valid session'
    - md: 'Delete: DELETE /auth google.protobuf.Empty , google.protobuf.Empty #Logout.'

It helps a lot to know the anatomy of a µService, read more here

Define the service in standard spec #

The standard specs have a much higher information density then the µSpecs. Furo will fill out as much as possible with good defaults by using the .furo configuration file.

It helps a lot to know the anatomy of a standard spec, read more here

When you generate the specs from µSpecs, Furo will generate all required types for the request and response in the same package that you have defined for your service. Furo will try to use the best defaults for the types. You can always edit this pre generated types.

File: specs/auth/AuthSession.service.spec

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

name: AuthSession
version: ""
description: Login with credentials. The service should set a auth cookie on successful login and delete it on logout
lifecycle: null
__proto:
  package: auth
  targetfile: authservice.proto
  imports:
    - google/api/annotations.proto
    - auth/reqmsgs.proto
    - auth/auth.proto
    - google/protobuf/empty.proto
  options:
    go_package: github.com/veith/doit-specs/dist/pb/auth;authpb
    java_multiple_files: "true"
    java_outer_classname: AuthserviceProto
    java_package: com.furo.baseauth
services:
  Create:
    description: 'Login with credentials #A login is nothing else then creating a valid session'
    data:
      request: auth.Credentials
      response: google.protobuf.Empty
      bodyfield: body
    deeplink:
      description: 'Create: POST /auth auth.Credentials , google.protobuf.Empty #Login with credentials #A login is nothing else then creating a valid session'
      href: /auth
      method: POST
      rel: create
    query: {}
    rpc_name: CreateAuthSession
  Delete:
    description: Logout.
    data:
      request: google.protobuf.Empty
      response: google.protobuf.Empty
      bodyfield: body
    deeplink:
      description: 'Delete: DELETE /auth google.protobuf.Empty , google.protobuf.Empty #Logout.'
      href: /auth
      method: DELETE
      rel: delete
    query: {}
    rpc_name: DeleteAuthSession

Resulting proto from the service definition #

The service itself #

file: dist/protos/auth/authservice.proto

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// Code generated by furo. DO NOT EDIT.

syntax = "proto3";
package auth;
option go_package = "github.com/veith/doit-specs/dist/pb/auth;authpb";
option java_multiple_files = true;
option java_outer_classname = "AuthserviceProto";
option java_package = "com.furo.baseauth";

import "auth/auth.proto";
import "auth/reqmsgs.proto";
import "google/api/annotations.proto";
import "google/protobuf/empty.proto";


// Login with credentials. The service should set a auth cookie on successful login and delete it on logout
service AuthSession {

    // Login with credentials #A login is nothing else then creating a valid session
    rpc CreateAuthSession (CreateAuthSessionRequest) returns (google.protobuf.Empty){
        //Create: POST /auth auth.Credentials , google.protobuf.Empty #Login with credentials #A login is nothing else then creating a valid session
        option (google.api.http) = {
		post: "/auth"
		body: "body"
	};
    }

    // Logout.
    rpc DeleteAuthSession (DeleteAuthSessionRequest) returns (google.protobuf.Empty){
        //Delete: DELETE /auth google.protobuf.Empty , google.protobuf.Empty #Logout.
        option (google.api.http) = {
		delete: "/auth"
		
	};
    }

}

The request messages #

file: dist/protos/auth/reqmsgs.proto

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

// Code generated by furo-proto-gen. DO NOT EDIT.
syntax = "proto3";
package auth;
option go_package = "github.com/veith/doit-specs/dist/pb/auth;authpb";
option java_multiple_files = true;
option java_outer_classname = "ReqmsgsProto";
option java_package = "com.furo.baseauth";

import "auth/auth.proto";
import "google/protobuf/empty.proto";


// request message for CreateAuthService
message CreateAuthServiceRequest {  

    // Body with auth.Credentials
    .auth.Credentials body = 1;
}

// request message for CreateAuthSession
message CreateAuthSessionRequest {  

    // Body with auth.Credentials
    .auth.Credentials body = 1;
}

// request message for CreateSessionAuthService
message CreateSessionAuthServiceRequest {  

    // Body with auth.Credentials
    .auth.Credentials body = 1;
}

// request message for DeleteAuthService
message DeleteAuthServiceRequest {  

    // Body with google.protobuf.Empty
    .google.protobuf.Empty body = 1;
}

// request message for DeleteAuthSession
message DeleteAuthSessionRequest {  

    // Body with google.protobuf.Empty
    .google.protobuf.Empty body = 1;
}

// request message for DeleteSessionAuthService
message DeleteSessionAuthServiceRequest {  

    // Body with google.protobuf.Empty
    .google.protobuf.Empty body = 1;
}