gonduit

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 12, 2016 License: MIT Imports: 10 Imported by: 11

README

gonduit GoDoc

A Go client for interacting with Phabricator via the Conduit API.

Currently this library is incomplete. This is a fork from https://github.com/jpoehls/go-conduit with support for some additional call and options. The library is a bit messy right now.

Getting started

Installing the library

A simple go get should do it:

go get github.com/etcinit/gonduit

For reproducible builds, you can also use Glide.

Authentication

Gonduit supports the following authentication methods:

  • tokens
  • session

If you are creating a bot/automated script, you should create a bot account on Phabricator rather than using your own.

tokens: Getting a conduit API token

To get an API token, go to https://{PHABRICATOR_URL}/settings/panel/apitokens/. From there, you should be able to create and copy an API token to use with the client.

session: Getting a conduit certificate

To get a conduit certificate, go to https://{PHABRICATOR_URL}/settings/panel/conduit. From there, you should be able to copy your certificate.

Basic Usage

Connecting

To construct an instance of a Gonduit client, use Dial with the URL of your install and an options object. Dial connects to the API, checks compatibility, and finally creates a Client instance:

client, err := gonduit.Dial(
	"https://phabricator.psyduck.info",
	&core.ClientOptions{
		APIToken: "api-SOMETOKEN"
	}
)

While certificate-based/session authentication is being deprecated in favor of API tokens, Gonduit still supports certificates in case you are using an older install. After calling Dial, you will also need to call client.Connect to create a session. The session key will be stored in the client itself and it will automatically be passed on on every subsequent request.

client, err := gonduit.Dial(
	"https://phabricator.psyduck.info",
	&core.ClientOptions{
		Cert: "CERTIFICATE",
		CertUser: "USERNAME",
	}
)

err = client.Connect()
Errors

Any conduit error response will be returned as a core.ConduitError type:

client, err := gonduit.Dial(
	"https://phabricator.psyduck.info",
	&core.ClientOptions{
		APIToken: "api-SOMETOKEN"
	}
)

ce, ok := err.(*core.ConduitError)
if ok {
	println("code: " + ce.Code())
	println("info: " + ce.Info())
}

// Or, use the built-in utility function:
if core.IsConduitError(err) {
	// do something else
}
Supported Calls

All the supported API calls are available in the Client struct. Every function is named after the Conduit method they call: For phid.query, we have Client.PHIDQuery. The same applies for request and responses: requests.PHIDQueryRequest and responses.PHIDQueryResponse.

Additionally, every general request method has the following signature:

func (c *Conn) ConduitMethodName(req Request) (Response, error)

Some methods may also have specialized functions, you should refer the GoDoc for more information on how to use them.

List of supported calls:
  • conduit.connect
  • conduit.query
  • differential.query
  • diffusion.querycommit
  • file.download
  • macro.creatememe
  • maniphest.query
  • maniphest.createtask
  • paste.create
  • paste.query
  • phid.lookup
  • phid.query
  • project.query
  • repository.query

Arbitrary calls

If you need to call an API method that is not supported by this client library, you can use the client.Call method to make arbitrary calls.

You will need to provide a struct with the request body and a struct for the response. The request has to be able to be able to be serialized into JSON, and the response has be able to be unserialized from JSON.

Request structs must also "extend" the requests.Request struct, which contains additional fields needed to authenticate with Conduit.

type phidLookupRequest struct {
	Names   []string         `json:"names"`
	requests.Request // Includes __conduit__ field needed for authentication.
}

type phidLookupResponse map[string]*struct{
	URI      string `json:"uri"`
	FullName string `json:"fullName"`
	Status   string `json:"status"`
}

req := &phidLookupRequest {
	Names: []string{"T1"},
	Session: client.Session,
}
var res phidLookupResponse

err := client.Call("phid.lookup", req, &res)

Documentation

Overview

Package gonduit provides a client for Phabricator's Conduit API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Conn

type Conn struct {
	Session *entities.Session
	// contains filtered or unexported fields
}

Conn is a connection to the conduit API.

func Dial

func Dial(host string, options *core.ClientOptions) (*Conn, error)

Dial connects to conduit and confirms the API capabilities for future calls.

func (*Conn) Call

func (c *Conn) Call(
	method string,
	params interface{},
	result interface{},
) error

Call allows you to make a raw conduit method call. Params will be marshalled as JSON and the result JSON will be unmarshalled into the result interface{}.

This is primarily useful for calling conduit endpoints that aren't specifically supported by other methods in this package.

func (*Conn) ConduitQuery added in v0.2.0

func (c *Conn) ConduitQuery() (*responses.ConduitQueryResponse, error)

ConduitQuery performs a call to conduit.query.

func (*Conn) Connect

func (c *Conn) Connect() error

Connect calls conduit.connect to open an authenticated session for future requests.

func (*Conn) DifferentialQuery

DifferentialQuery performs a call to differential.query.

func (*Conn) DiffusionQueryCommits

DiffusionQueryCommits performs a call to diffusion.querycommits.

func (*Conn) FileDownload

FileDownload performs a call to file.download.

func (*Conn) MacroCreateMeme

MacroCreateMeme performs a call to macro.creatememe.

func (*Conn) ManiphestCreateTask added in v0.2.0

func (c *Conn) ManiphestCreateTask(
	req requests.ManiphestCreateTaskRequest,
) (*entities.ManiphestTask, error)

ManiphestCreateTask performs a call to maniphest.createtask.

func (*Conn) ManiphestQuery

ManiphestQuery performs a call to maniphest.query.

func (*Conn) PHIDLookup

PHIDLookup calls the phid.lookup endpoint.

func (*Conn) PHIDLookupSingle

func (c *Conn) PHIDLookupSingle(name string) (*entities.PHIDResult, error)

PHIDLookupSingle calls the phid.lookup endpoint with a single name.

func (*Conn) PHIDQuery

PHIDQuery calls the phid.query endpoint.

func (*Conn) PHIDQuerySingle

func (c *Conn) PHIDQuerySingle(phid string) (*entities.PHIDResult, error)

PHIDQuerySingle calls the phid.query endpoint with a single phid.

func (*Conn) PasteCreate

PasteCreate calls the paste.create endpoint.

func (*Conn) PasteQuery

PasteQuery calls the paste.query endpoint.

func (*Conn) ProjectQuery

ProjectQuery performs a call to project.query.

func (*Conn) RepositoryQuery

RepositoryQuery performs a call to repository.query.

type Dialer

type Dialer struct {
	ClientName        string
	ClientVersion     string
	ClientDescription string
}

A Dialer contains options for connecting to an address.

func (*Dialer) Dial

func (d *Dialer) Dial(
	host string,
	options *core.ClientOptions,
) (*Conn, error)

Dial connects to conduit and confirms the API capabilities for future calls.

Directories

Path Synopsis
test

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL