Project: Harbor (Provisioning / Container Registry)
File: README.md

In Stratoscale, we really like the idea of API-first services, and we also really like Go. We saw the go-swagger library, and thought that most of it can really help us. Generating code from swagger files is a big problem with a lot of corner cases, and go-swagger is doing great job. The one thing that we felt missing, is customization of the server to run with our design principles: Custom `main` function Dependency injection Limited scopes with unit testing. Also: Adding you functions to the generated `configure_swagger_.go` seems to be a burden. Lack of Interface that the service implement. Complicated and custom http clients and runtime. Those are the changes that this contributor templates are providing: Those interfaces can implemented by the developer and are the business logic of the service. The implementation of those is extensible. The implementation is separated from the generated code. The `restapi.Handler` (see ) function returns a standard `http.Handler` Given objects that implements the business logic, we can create a simple http handler. This handler is standard go http.Handler, so we can now use any other middleware, library, or framework that support it. This handler is standard, so we understand it better. The new client package exposes interfaces, so functions in our code can receive those interfaces which can be mocked for testing. The new client has a config that gets an `url.URL` to customize the endpoint. The new client has a config that gets an `http.RoundTripper` to customize client with libraries, middleware or frameworks that support the standard library's objects. In the you'll find generated code and usage of the pet-store . The `restapi`, `models` and `client` are auto-generated by the stratoscale/swagger docker file. The `internal` package was manually added and contains the server's business logic. The `main.go` file is the entrypoint and contains initializations and dependency injections of the project. This package is autogenerated and contains the server routing and parameters parsing. The modified version contains `restapi.PetAPI` and `restapi.StoreAPI` which were auto generated. ```go // PetAPI type PetAPI interface { PetCreate(ctx context.Context, params pet.PetCreateParams) middleware.Responder PetDelete(ctx context.Context, params pet.PetDeleteParams) middleware.Responder PetGet(ctx context.Context, params pet.PetGetParams) middleware.Responder PetList(ctx context.Context, params pet.PetListParams) middleware.Responder PetUpdate(ctx context.Context, params pet.PetUpdateParams) middleware.Responder } //go:generate mockery -name StoreAPI -inpkg // StoreAPI type StoreAPI interface { InventoryGet(ctx context.Context, params store.InventoryGetParams) middleware.Responder OrderCreate(ctx context.Context, params store.OrderCreateParams) middleware.Responder // OrderDelete is For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors OrderDelete(ctx context.Context, params store.OrderDeleteParams) middleware.Responder // OrderGet is For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions OrderGet(ctx context.Context, params store.OrderGetParams) middleware.Responder } ``` Each function matches an `operationId` in the swagger file and they are grouped according to the operation `tags`. There is also a `restapi.Config`: ```go // Config is configuration for Handler type Config struct { PetAPI StoreAPI Logger func(string, ...interface{}) // InnerMiddleware is for the handler executors. These do not apply to the swagger.json document. // The middleware executes after routing but before authentication, binding and validation InnerMiddleware func(http.Handler)

} ``` This config is auto generated and contains all the declared interfaces above. It is used to initiate an http.Handler with the `Handler` function: ```go // Handler returns an http.Handler given the handler configuration // It mounts all the business logic implementers in the right routing. func Handler(c Config) (http.Handler, error) { ... ``` Let's look how we use this generated code to build our server. The `internal` package is not auto generated and contains the business logic of our server. We can see two structs that implements the `restapi.PetAPI` and `restapi.StoreAPI` interfaces, needed to make our server work. When adding or removing functions from our REST API, we can just add or remove functions to those business logic units. We can also create new logical units when they are added to our REST API. The main function is pretty straight forward. We initiate our business logic units. Then create a config for our rest API. We then create a standard `http.Handler` which we can update with middleware, test with `httptest`, or to use with other standard tools. The last piece is to run the handler with `http.ListenAndServe` or to use it with an `http.Server` - it is all very customizable. ```go func main() { // Initiate business logic implementers. // This is the main function, so here the implementers' dependencies can be // injected, such as database, parameters from environment variables, or different // clients for different APIs. p := internal.Pet{} s := internal.Store{} // Initiate the http handler, with the objects that are implementing the business logic. h, err := restapi.Handler(restapi.Config{ PetAPI: &p, StoreAPI: &s, Logger: log.Printf, }) if err != nil { log.Fatal(err) } // Run the standard http server log.Fatal(http.ListenAndServe(":8080", h)) } ``` The client code is in the and is autogenerated. To create a new client we use the `client.Config` struct: ```go type Config struct { // URL is the base URL of the upstream server URL *url.URL // Transport is an inner transport for the client Transport http.RoundTripper } ``` This enables us to use custom server endpoint or custom client middleware. Easily, with the standard components, and with any library that accepts them. The client is then generated with the New method: ```go // New creates a new swagger petstore HTTP client. func New(c Config) *SwaggerPetstore { ... } ``` This method returns an object that has two important fields: ```go type SwaggerPetstore { ... Pet *pet.Client Store *store.Client } ``` Those fields are objects, which implements interfaces declared in the and packages: For example: ```go // API is the interface of the pet client type API interface { // PetCreate adds a new pet to the store PetCreate(ctx context.Context, params PetCreateParams) (PetCreateCreated, error) // PetDelete deletes a pet PetDelete(ctx context.Context, params PetDeleteParams) (PetDeleteNoContent, error) // PetGet gets pet by it s ID PetGet(ctx context.Context, params PetGetParams) (PetGetOK, error) // PetList lists pets PetList(ctx context.Context, params PetListParams) (PetListOK, error) // PetUpdate updates an existing pet PetUpdate(ctx

params PetUpdateParams) (PetUpdateCreated, error) } ``` They are very similar to the server interfaces, and can be used by consumers of those APIs (instead of using the actual client or the `*Pet` struct) Authenticating and policy enforcement of the application is done in several stages, described below. Add to the root of the swagger.yaml the security and security definitions sections. ```yaml securityDefinitions: token: type: apiKey in: header name: Cookie security: token: [] ``` The securityDefinitions section defines different security types that your application can handle. The supported types by go-swagger are: `apiKey` - token that should be able to processed. `oauth2` - token and scopes that should be processed. and `basic` - user/password that should be processed. Here we defined an apiKey, that is passed through the Cookie header. The `security` section defines the default security enforcement for the application. You can select different securityDefinitions, as the keys, and apply "scopes" as the values. Those default definitions can be overridden in each route by a section with the same name: ```yaml paths: /pets: post: [...] security: token: [admin] ``` Here we overridden the scope of token in the POST /pets URL so that only admin can use this API. Let's see how we can use this functionality. Once we created a security definition named "token", a function called "AuthToken" was added to the `restapi.Config`: ```go type Config struct { ... // AuthToken Applies when the "Cookie" header is set AuthToken func(token string) (interface{}, error) } ``` This function gets the content of the Cookie header, and should return an `interface{}` and `error`. The `interface{}` is the object that should represent the user that performed the request, it should be nil to return an unauthorized 401 HTTP response. If the returned `error` is not nil, an HTTP 500, internal server error will be returned. The returned object, will be stored in the request context under the `restapi.AuthKey` key. There is another function that we should know about, in the `restapi.Config` struct: ```go type Config struct { ... // Authorizer is used to authorize a request after the Auth function was called using the "Auth*" functions // and the principal was stored in the context in the "AuthKey" context value. Authorizer func(*http.Request) error } ``` This one is a custom defined function that gets the request and can return an error. If the returned error is not nil, and 403 HTTP error will be returned to the client - here the policy enforcement comes to place. There are two things that this function should be aware of: The user - it can retrieve the user information from the context: `ctx.Value(restapi.AuthKey).(MyUserType)`. Usually, a server will have a function for extracting this user information and returns a concrete type which could be used by all the routes. The route - it can retrieve the route using the go-swagger function: `middleware.MatchedRouteFrom(*http.Request)`. So no need to parse URL and test the request method. This route struct contains the route information. If for example, we want to check the scopes that were defined for the current route in the swagger.yaml we can use the code below: ```go for _, auth := range route.Authenticators { for scopeName, scopeValues := range auth.Scopes { for _, scopeValue := range scopeValues { ... } } } ```