-
Notifications
You must be signed in to change notification settings - Fork 281
/
doc.go
119 lines (118 loc) · 4.03 KB
/
doc.go
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
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
// Copyright (c) 2017 Uber Technologies, Inc.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
// Package service is the Service.
//
// Service, being a bit of an overloaded term, requires some
// specific care to explain the various components in the
// servicepackage in UberFx.
//
//
// Core
//
// This model results in a simple, consistent way to start a service. For example,
// in the case of a simple TChannel Service,
// main.go might look like this:
//
// package main
//
// import (
// "go.uber.org/fx/config"
// "go.uber.org/fx/modules/yarpc"
// "go.uber.org/fx/service"
// )
//
// func main() {
// // Create the service object
// svc, err := service.WithModule(
// // The list of module creators for this service
// yarpc.New(yarpc.ServiceCreateFunc(NewYarpcThriftHandler)),
// ).Build()
//
// if err != nil {
// log.Fatal("Could not initialize service: ", err)
// }
//
// // Start the service, with "true" meaning:
// // * Wait for service exit
// // * Report a non-zero exit code if shutdown is caused by an error
// svc.Start(true)
// }
//
// Roles
//
// It's common for a service to handle many different workloads. For example, a
// service may expose RPC endpoints and also ingest Kafka messages.
//
//
// In UberFX, there is a simpler model where we create a single binary,
// but turn its modules on and off based on roles which are specified via the
// command line.
//
//
// For example, imagine we wanted a "worker" and a "service" role that handled
// Kafka and TChannel, respectively:
//
//
// func main() {
// svc, err := service.WithModule(
// kafka.Module("kakfa_topic1", []string{"worker"}),
// ).WithModule(
// yarpc.New(yarpc.ServiceCreateFunc(NewYarpcThriftHandler)),
// service.WithRole("service"),
// ).Build()
//
// if err != nil {
// log.Fatal("Could not initialize service: ", err)
// }
//
// svc.Start()
// }
//
// Which then allows us to set the roles either via a command line variable:
//
// export CONFIG__roles__0=worker
//
// Or via the service parameters, we would activate in the following ways:
//
// • ./myservice or ./myservice --roles "service,worker": Runs all modules
//
// • ./myservice --roles "worker": Runs only the Kakfa module
//
// • Etc...
//
// Options
//
// The service builder takes a variadic Optionspattern, allowing you to pick and choose which components you'd like to
// override. As a common theme of UberFx, specifying zero options should give
// you a fully working application.
//
//
// Once you have a service, you call .Start() on it to begin receiving requests.
//
// Start(bool) comes in two variants: a blocking version and a non-blocking
// version. In our sample apps, we use the blocking version (
// svc.Start(true)) and
// yield control to the service lifecycle manager. If you wish to do other things
// after starting your service, you may pass
// false and use the return values of
// svc.Start(bool) to listen on channels and trigger manual shutdowns.
//
//
package service