README.md

# Maps Booking

This repo contains tools and code samples for partners that wish to integrate
with [Reserve](https://www.google.com/maps/reserve/)

## Testing Client

Before using the test utility, the Go programming language must be installed
on your workstation. A precompiled Go binary for your operating system can
be [found here](https://golang.org/dl/)

This guide will assume you're using the default GOPATH and subsequent GOBIN.
For a comprehensive explanation of the GOPATH env variable please see
[this document](https://golang.org/dl/) by the Go team.

### Installing the utility with Linux

First, build your Go directory structure. A comprehensive guide on the intended
structure of Go code can be [found here.](https://golang.org/doc/code.html)

    mkdir -p $HOME/go/bin $HOME/go/pkg $HOME/go/src/github.com/maps-booking

Next, add the following to your ~/.bashrc

    export PATH=$PATH:$(go env GOPATH)/bin
    export GOPATH=$(go env GOPATH)
    export GOBIN=$(go env GOPATH)/bin

Source changes

    source ~/.bashrc

Next, retrieve the utility from the
[maps-booking repository](https://maps-booking.googlesource.com/)

    git clone https://maps-booking.googlesource.com/test_client $HOME/go/src/github.com/maps-booking/

Lastly, download all dependencies and install the tool.

    cd $HOME/go
    go get -d ./...
    go install $HOME/go/src/github.com/maps-booking/testclient/main.go

### Installing the utility with Windows Powershell

First, build your Go directory structure. A comprehensive guide on the intended
structure of Go code can be [found here.](https://golang.org/doc/code.html)

    $env:HOME = $env:USERPROFILE
    md $env:HOME\go\bin
    md $env:HOME\go\pkg
    md $env:HOME\go\src\github.com\maps-booking

Next, set the appropriate environment variables

    $env:PATH = $env:PATH + ";" + (go env GOPATH) + "\bin"
    $env:GOPATH = (go env GOPATH)
    $env:GOBIN = (go env GOPATH) + "\bin"

Next, retrieve the utility from the
[maps-booking repository](https://maps-booking.googlesource.com/)

    git clone https://maps-booking.googlesource.com/test_client $env:HOME\go\src\github.com\maps-booking\

Lastly, download all dependencies and install the tool.

    cd $env:HOME\go
    go get -d .\...
    go install $env:HOME\go\src\github.com\maps-booking\testclient\main.go

### Using the utility

After following the install steps above an executable should now live in

    $HOME/go/bin/main

or

    $env:HOME\go\bin\main.exe

All available flags can be displayed using the '--help' flag. The currently
accepted flags are:

    -all_tests
        Whether to test all endpoints.
    -availability_feed string
        Absolute path to availability feed required for all tests except health.
        Feeds can be in either json or pb3 format
    -booking_status_test
        Whether to test the GetBookingStatus endpoint.
    -booking_test
        Whether to test the CreateBooking endpoint.
    -ca_file string
        Absolute path to your server's Certificate Authority root cert.
        Downloading all roots currently recommended by the Google Internet
        Authority is a suitable alternative https://pki.google.com/roots.pem
    -cancel_all_bookings
        This option assumes that the ListBookings and UpdateBooking endpoints
        are fully functional. This is a convenience flag for purging your system
        of all previously created bookings.
    -check_availability_test
        Whether to test the CheckAvailability endpoint.
    -health_check_test
        Whether to test the Health endpoint.
    -list_bookings_test
        Whether to test the ListBookings endpoint
    -num_test_slots int
        Maximum number of slots to test from availability_feed. Slots will be
        selected randomly (default 10)
    -output_dir string
        Absolute path of dir to dump log file.
    -rescheduling_test
        Whether to test the UpdateBooking endpoint.
    -rpc_timeout duration
        Number of seconds to wait before abandoning request (default 30s)
    -server_addr string
        Your grpc server's address in the format of host:port
        (default "example.com:80")
    -servername_override string
        Override FQDN to use. Please see README for additional details
    -tls
        Whether to enable TLS when using the test client. Please review the
        README.md before attempting to use this flag.

Example Usage:

    bin/main -health_check_test=true -check_availability_test=true
    -output_dir="/tmp" -server_addr="grpc-service.google.com:50051”
    -availability_feed="/tmp/test.json"

#### Enabling TLS
Using the TLS feature of this utility is slightly more complicated than the
standard non-TLS runs and requires a few additional steps.

- Begin by overriding your server's RootCAs file with the provided root.pem
  located in maps-booking/certs/root.pem. Details regarding your server's root
  certs can be found on the [maps-booking developer site.]
  (https://developers.google.com/maps-booking/guides/partner-implementing-grpc-server-2)

- Point the ca_file flag of the client utility to the location of your original
  roots file. If you don't have one yet you can [download these
  roots](https://pki.google.com/roots.pem) that have been recommended by the
  Google Internet Authority.

- Enable TLS by setting the tls flag to true.

Example Usage:

    bin/main -health_check_test=true -check_availability_test=true
    -output_dir="/tmp" -server_addr="grpc-service.google.com:50051”
    -availability_feed="/tmp/test.json" -tls -ca_file="/tmp/trusted_roots.pem"

#### Optional TLS Feature

It's possible to override the FQDN your client attempts to use during the TLS
handshake. If you find a need to use an alias when testing your implementation,
simply override using the servername_override flag.

Example Usage:

    bin/main -health_check_test=true -check_availability_test=true
    -output_dir="/tmp" -server_addr="localhost:50051”
    -availability_feed="/tmp/test.json" -tls -ca_file="/tmp/trusted_roots.pem"
    -servername_override="myservice.google.com"


### Parsing the output

The test utility will output a file with the prefix 'grpc_test_client_log_'
followed by a timestamp in RFC3339 format. The output file contains a
complete log of all Requests and Responses sent/received by the testing tool as
well as diffs of the expected response in the event of errors.
Similar to a compiler, an overview of the entire run can be found at the end
of the file for user friendly digestion.