grafton

README

Manifold's provider validation tool

Code of Conduct | Contribution Guidelines | CHANGELOG

Introduction

Grafton is a super simple CLI tool used by service providers (and Manifold) to test their integrations with Manifold.

Using this CLI tool, a provider can test the following:

• Provisioning of a Resource
• Provisioning of Credentials
• Resizing of a Resource
• Pulling Resource Measures (optional)
• Deprovisioning of Credentials
• Deprovisioning of a Resource

Requests generated by Grafton are the exact same shape and style as those made by the Provisioning service. Using this tool, a provider should be able to implement and test their integration without needing real requests from any Manifold services.

Installation

Precompiled binaries are build for each release of Grafton for the following platforms:

• linux / amd64
• darwin (macos) / amd64
• windows / amd64

The zip files of these binaries are in the downloads section of each release (i.e. the latest release).

To install, download and unzip the appropriate binary for your system, and run the grafton program inside. You may want to add it to a directory in your PATH for ease of use.

Usage

1. Generate Keypair

To use, a provider must generate a local public keypair used for signing ephemereal live keypairs. This allows Grafton to generate and sign requests using the same algorithms as Manifold.

$ grafton generate

When a keypair is generated it will be written to a masterkey.json file in the current working directory.

The public key contained in this file can be used by the implemented service to verify the authenticity of the requests made by Grafton

1. Run Tests

Now that a key has been generated, you can run the tests which will provision a resource, create credentials, create another set of credentials, and then deprovision those before resizing the resource. Finally, Grafton will deprovision the resource.

grafton test --product=bonnets --plan=small --region=aws::us-east-1 \
    --client-id=21jtaatqj8y5t0kctb2ejr6jev5w8 \
    --client-secret=3yTKSiJ6f5V5Bq-kWF0hmdrEUep3m3HKPTcPX7CdBZw \
    --connector-port=3001 \
    --new-plan=large \
    http://localhost:4567

Excluding Features

When testing it is possible to exclude of one more features from being run. To disable Resource Measures and Resize, for example, you can pass: --exclude resource-measures plan-change.

Releasing

Releasing grafton is a manual process run on a developers local machine.

1. Ensure all of the required code has been merged into master.
2. Determine whether or not the CHANGELOD.md is up to date and correct for this release, if it's not, update it!
3. Create a tag off master (following semver), which includes the up to date CHANGELOG.md (and matches the remote sha of master on github).
4. Build grafton locally from scratch (make clean; make)
5. Create the build zips (make zips)
6. Create a release on github for the tag which includes the changelog for this release and upload the build zips.
7. Done!

On editing the OpenAPI spec

provider.yaml is a manual copy of an internally generated file. It, in turn, is used to generate the client code under generated.

Until we automate more of this, the following has to be kept in mind:

• Any changes to provider.yaml should not be merged here directly, but instead ported to the internal file first.
• If the internal source of provider.yaml changes, the updates must be brought over here.
• Whenever provider.yaml changes, make generated-clients should be run, and the changes to the generated code should be checked in.

Documentation

Overview

Package grafton provides A simple interface to the provider api. it is used both within the grafton test tool, and by our own internal services.

Index

• Constants
• Variables
• func CreateSsoURL(base *nurl.URL, code string, resourceID manifold.ID) *nurl.URL
• func IsFatal(err error) bool
• func NewErrWithMsg(t merrors.Type, m *string) error
• func ToError(err error) manifold.HTTPError
• func ValidCredentialName(name string) bool
• type Client
  • func New(url *nurl.URL, connectorURL *nurl.URL, signer Signer, log *logrus.Entry) *Client
  • func (c *Client) ChangePlan(ctx context.Context, cbID, resourceID manifold.ID, newPlan string, ...) (string, bool, error)
  • func (c *Client) CreateSsoURL(code string, resourceID manifold.ID) *nurl.URL
  • func (c *Client) DeprovisionCredentials(ctx context.Context, cbID, credentialID manifold.ID) (string, bool, error)
  • func (c *Client) DeprovisionResource(ctx context.Context, cbID, resourceID manifold.ID) (string, bool, error)
  • func (c *Client) ProvisionCredentials(ctx context.Context, cbID, resID, credID manifold.ID) (map[string]string, string, bool, error)
  • func (c *Client) ProvisionResource(ctx context.Context, cbID, resID manifold.ID, product, plan, region string, ...) (string, bool, error)
  • func (c *Client) PullResourceMeasures(ctx context.Context, rid manifold.ID, start, end time.Time) (*models.ResourceMeasures, error)
• type Error
  • func NewError(t merrors.Type, m string) *Error
  • func (e *Error) Error() string
  • func (e *Error) StatusCode() int
  • func (e *Error) WriteResponse(rw http.ResponseWriter, pr runtime.Producer)
• type Signer

Constants

const NameRegexpString = "^[A-Z][A-Z0-9_]{0,127}$"

NameRegexpString is the string form of a regular expression for determining if a credential name is valid or not.

Specified in Shell and Utilities volume of IEEE 1003.1-2001.

Variables

var ErrMissingMsg = errors.New("`message` field was missing from the response")

ErrMissingMsg occurs when a provider's response is missing the Message field

Functions

func CreateSsoURL

func CreateSsoURL(base *nurl.URL, code string, resourceID manifold.ID) *nurl.URL

CreateSsoURL generates and returns a *url.URL to initiate a single sign-on request against the provided base url, code, and resourceID.

func IsFatal

func IsFatal(err error) bool

IsFatal returns true or false depending on whether or not the given error is considered to be fatal

func NewErrWithMsg

func NewErrWithMsg(t merrors.Type, m *string) error

NewErrWithMsg creates a new Error from a string pointer, if the pointer is nil then an ErrMissingMsg is returned instead.

func ToError

func ToError(err error) manifold.HTTPError

ToError receives an error and mutates it into a grafton.Error based on the concrete type of the error.

func ValidCredentialName

func ValidCredentialName(name string) bool

ValidCredentialName returns true or false depending on whether or not the given name is a valid credential name.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a wrapper around the generated provisioning api client, providing convenience methods, and signing outgoing requests.

func New

func New(url *nurl.URL, connectorURL *nurl.URL, signer Signer, log *logrus.Entry) *Client

New creates a new Client

func (*Client) ChangePlan

func (c *Client) ChangePlan(ctx context.Context, cbID, resourceID manifold.ID, newPlan string,
	features map[string]interface{}) (string, bool, error)

ChangePlan makes a patch call to change the resource's plan.

A message will be returned if a callback was used *or* a provider returned an error with an explanation.

func (*Client) CreateSsoURL

func (c *Client) CreateSsoURL(code string, resourceID manifold.ID) *nurl.URL

CreateSsoURL Generates and returns a *url.URL to initiate single sign-on against the provider for this client.

func (*Client) DeprovisionCredentials

func (c *Client) DeprovisionCredentials(ctx context.Context, cbID, credentialID manifold.ID) (string, bool, error)

DeprovisionCredentials deletes credentials from the remote provider.

A message will be presented if a callback is provided or if a message was returned from the provider due to an error.

func (*Client) DeprovisionResource

func (c *Client) DeprovisionResource(ctx context.Context, cbID, resourceID manifold.ID) (string, bool, error)

DeprovisionResource deletes resources from the remote provider.

A message will be returned if a callback was used *or* a provider returned an error with an explanation.

func (*Client) ProvisionCredentials

func (c *Client) ProvisionCredentials(ctx context.Context, cbID, resID, credID manifold.ID) (map[string]string, string, bool, error)

ProvisionCredentials makes a credential provisioning call.

A message will be returned if a callback was used *or* a provider returned an error with an explanation.

func (*Client) ProvisionResource

func (c *Client) ProvisionResource(ctx context.Context, cbID, resID manifold.ID, product, plan,
	region string, features map[string]interface{}) (string, bool, error)

ProvisionResource makes a resource provisioning call.

A message will be returned if a callback was used *or* a provider returned an error with an explanation.

func (*Client) PullResourceMeasures

func (c *Client) PullResourceMeasures(ctx context.Context, rid manifold.ID,
	start, end time.Time) (*models.ResourceMeasures, error)

PullResourceMeasures tries to get information about a resource usage.

type Error

type Error struct {
	Type    merrors.Type `json:"error"`
	Message string       `json:"message"`
}

Error is the error type we'll use for providers to return.

func NewError

func NewError(t merrors.Type, m string) *Error

NewError creates a new Error with a type and message.

func (*Error) Error

func (e *Error) Error() string

Error returns the message of the error.

func (*Error) StatusCode

func (e *Error) StatusCode() int

StatusCode returns the StatusCode for the current error type.

func (*Error) WriteResponse

func (e *Error) WriteResponse(rw http.ResponseWriter, pr runtime.Producer)

WriteResponse completes the interface for a HTTPError; enabling an error to be returned as a middleware.Responder from go-openapi/runtime

A panic will occur if the given producer errors.

type Signer

type Signer interface {
	Sign([]byte) (*signature.Signature, error)
}

Signer is the interface used to sign outgoing request payloads.