gonduit

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Apr 18, 2024 License: MIT Imports: 14 Imported by: 2

README

gonduit GoDoc

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

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",
		Timeout: 10 * time.Second,
	},
)

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
  • maniphest.gettasktransactions
  • paste.create
  • paste.query
  • phid.lookup
  • phid.query
  • phriction.info
  • project.query
  • remarkup.process
  • repository.query
  • user.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 DialFromArcrc added in v0.3.0 

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

DialFromArcrc connects to conduit. If the API token is not set on the options, it attempts to load one from ~/.arcrc.

func (*Conn) AlmanacBindingEdit added in v0.3.0 

func (c *Conn) AlmanacBindingEdit(req requests.EditRequest) (*responses.EditResponse, error)

AlmanacBindingEdit performs a call to almanac.binding.edit

func (*Conn) AlmanacBindingSearch added in v0.3.0 

func (c *Conn) AlmanacBindingSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

AlmanacBindingSearch performs a call to almanac.binding.search

func (*Conn) AlmanacDeviceEdit added in v0.3.0 

func (c *Conn) AlmanacDeviceEdit(req requests.EditRequest) (*responses.EditResponse, error)

AlmanacDeviceEdit performs a call to almanac.device.edit

func (*Conn) AlmanacDeviceSearch added in v0.3.0 

func (c *Conn) AlmanacDeviceSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

AlmanacDeviceSearch performs a call to almanac.device.search

func (*Conn) AlmanacInterfaceEdit added in v0.3.0 

func (c *Conn) AlmanacInterfaceEdit(req requests.EditRequest) (*responses.EditResponse, error)

AlmanacInterfaceEdit performs a call to almanac.interface.edit

func (*Conn) AlmanacInterfaceSearch added in v0.3.0 

func (c *Conn) AlmanacInterfaceSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

AlmanacInterfaceSearch performs a call to almanac.interface.search

func (*Conn) AlmanacNetworkEdit added in v0.3.0 

func (c *Conn) AlmanacNetworkEdit(req requests.EditRequest) (*responses.EditResponse, error)

AlmanacNetworkEdit performs a call to almanac.network.edit

func (*Conn) AlmanacNetworkSearch added in v0.3.0 

func (c *Conn) AlmanacNetworkSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

AlmanacNetworkSearch performs a call to almanac.network.search

func (*Conn) AlmanacServiceEdit added in v0.3.0 

func (c *Conn) AlmanacServiceEdit(req requests.EditRequest) (*responses.EditResponse, error)

AlmanacServiceEdit performs a call to almanac.service.edit

func (*Conn) AlmanacServiceSearch added in v0.3.0 

func (c *Conn) AlmanacServiceSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

AlmanacServiceSearch performs a call to almanac.service.search

func (*Conn) BadgeEdit added in v0.3.0 

func (c *Conn) BadgeEdit(req requests.EditRequest) (*responses.EditResponse, error)

func (*Conn) BadgeSearch added in v0.3.0 

func (c *Conn) BadgeSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

BadgeSearch performs a call to badge.search

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) DifferentialDiffSearch added in v0.3.0 

func (c *Conn) DifferentialDiffSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

DifferentialDiffSearch performs a call to differential.diff.search

func (*Conn) DifferentialGetRawDiff added in v0.3.0 

func (c *Conn) DifferentialGetRawDiff(req requests.DifferentialGetRawDiffRequest) (*responses.DifferentialGetRawDiffResponse, error)

DifferentialGetRawDiff performs a call to differential.getrawdiff

func (*Conn) DifferentialQuery 

func (c *Conn) DifferentialQuery(
	req requests.DifferentialQueryRequest,
) (*responses.DifferentialQueryResponse, error)

DifferentialQuery performs a call to differential.query. Deprecated: This method is frozen and will eventually be deprecated. New code should use "differential.revision.search" instead.

func (*Conn) DifferentialQueryDiffs added in v0.3.0 

func (c *Conn) DifferentialQueryDiffs(req requests.DifferentialQueryDiffsRequest) (responses.DifferentialQueryDiffsResponse, error)

DifferentialQueryDiffs performs a call to differential.querydiffs. Deprecated: This method is frozen and will eventually be deprecated. New code should use "differential.diff.search" instead.

func (*Conn) DifferentialRevisionEdit added in v0.3.0 

func (c *Conn) DifferentialRevisionEdit(req requests.EditRequest) (*responses.EditResponse, error)

DifferentialRevisionEdit performs a call to differential.revision.edit

func (*Conn) DifferentialRevisionSearch added in v0.3.0 

func (c *Conn) DifferentialRevisionSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

DifferentialRevisionSearch performs a call to differential.revision.search

func (*Conn) DiffusionBranchQuery added in v0.3.0 

func (c *Conn) DiffusionBranchQuery(req requests.DiffusionBranchQueryRequest) (*responses.DiffusionBranchQueryResponse, error)

DiffusionBranchQuery performs a call to diffusion.branchquery

func (*Conn) DiffusionCommitParentsQuery added in v0.3.0 

func (c *Conn) DiffusionCommitParentsQuery(req requests.CommitParentsQueryRequest) (*responses.CommitParentsQueryResponse, error)

DiffusionCommitParentsQuery performs a call to diffusion.commitparentsquery

func (*Conn) DiffusionCommitSearch added in v0.3.0 

func (c *Conn) DiffusionCommitSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

DiffusionCommitSearch performs a call to diffusion.commit.search

func (*Conn) DiffusionFileContentQuery added in v0.3.0 

func (c *Conn) DiffusionFileContentQuery(req requests.FileContentQueryRequest) (*responses.FileContentQueryResponse, error)

DiffusionFileContentQuery performs a call to diffusion.filecontentquery

func (*Conn) DiffusionQueryCommits 

func (c *Conn) DiffusionQueryCommits(
	req requests.DiffusionQueryCommitsRequest,
) (*responses.DiffusionQueryCommitsResponse, error)

DiffusionQueryCommits performs a call to diffusion.querycommits. Deprecated: This method is frozen and will eventually be deprecated. New code should use "diffusion.commit.search" instead.

func (*Conn) DiffusionRepositorySearch added in v0.3.0 

func (c *Conn) DiffusionRepositorySearch(req requests.SearchRequest) (*responses.SearchResponse, error)

DiffusionRepositorySearch performs a call to diffusion.repository.search

func (*Conn) DiffusionResolveRefs added in v0.3.0 

func (c *Conn) DiffusionResolveRefs(req requests.ResolveRefsRequest) (*responses.ResolveRefsResponse, error)

DiffusionResolveRefs performs a call to diffusion.resolverefs

func (*Conn) EdgeSearch added in v0.3.0 

func (c *Conn) EdgeSearch(req requests.EdgeSearchRequest) (*responses.EdgeSearchResponse, error)

EdgeSearch performs a call to edge.search endpoint to find object associations.

func (*Conn) FileDownload 

func (c *Conn) FileDownload(
	req requests.FileDownloadRequest,
) (*responses.FileDownloadResponse, error)

FileDownload performs a call to file.download.

func (*Conn) FileSearch added in v0.3.0 

func (c *Conn) FileSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

FileSearch performs a call to file.search

func (*Conn) HarbormasterBuildableSearch added in v0.3.0 

func (c *Conn) HarbormasterBuildableSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

HarbormasterBuildableSearch performs a call to harbormaster.buildable.search.

func (*Conn) HarbormasterCreateArtifact added in v0.3.0 

func (c *Conn) HarbormasterCreateArtifact(req requests.HarbormasterCreateArtifactRequest) (*responses.HarbormasterCreateArtifactResponse, error)

HarbormasterCreateArtifact performs a call to harbormaster.createartifact.

func (*Conn) HarbormasterSendMessage added in v0.3.0 

func (c *Conn) HarbormasterSendMessage(req requests.HarbormasterSendMessageRequest) (*responses.HarbormasterSendMessageResponse, error)

HarbormasterSendMessage performs a call to harbormaster.sendmessage.

func (*Conn) MacroCreateMeme 

func (c *Conn) MacroCreateMeme(
	req requests.MacroCreateMemeRequest,
) (*responses.MacroCreateMemeResponse, error)

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. Deprecated: This method is frozen and will eventually be deprecated. New code should use "maniphest.edit" instead.

func (*Conn) ManiphestEdit added in v0.3.0 

func (c *Conn) ManiphestEdit(req requests.EditRequest) (*responses.EditResponse, error)

ManiphestEdit performs a call to maniphest.edit

func (*Conn) ManiphestGetTaskTransactions added in v0.3.0 

func (c *Conn) ManiphestGetTaskTransactions(
	req requests.ManiphestGetTaskTransactions,
) (*responses.ManiphestGetTaskTransactionsResponse, error)

ManiphestGetTaskTransactions performs a call to maniphest.gettasktransactions Deprecated: This method is frozen and will eventually be deprecated. New code should use "transaction.search" instead.

func (*Conn) ManiphestQuery 

func (c *Conn) ManiphestQuery(
	req requests.ManiphestQueryRequest,
) (*responses.ManiphestQueryResponse, error)

ManiphestQuery performs a call to maniphest.query. Deprecated: This method is frozen and will eventually be deprecated. New code should use "maniphest.search" instead.

func (*Conn) ManiphestSearch added in v0.3.0 

func (c *Conn) ManiphestSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

ManiphestSearch performs a call to maniphest.search

func (*Conn) ManiphestStatusSearch added in v0.3.0 

func (c *Conn) ManiphestStatusSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

ManiphestStatusSearch performs a call to maniphest.status.search

func (*Conn) OwnersSearch added in v0.3.0 

func (c *Conn) OwnersSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

OwnersSearch performs a call to owners.search

func (*Conn) PHIDLookup 

func (c *Conn) PHIDLookup(
	req requests.PHIDLookupRequest,
) (responses.PHIDLookupResponse, error)

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 

func (c *Conn) PHIDQuery(
	req requests.PHIDQueryRequest,
) (responses.PHIDQueryResponse, error)

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 

func (c *Conn) PasteCreate(
	req *requests.PasteCreateRequest,
) (responses.PasteCreateResponse, error)

PasteCreate calls the paste.create endpoint. Deprecated: This method is frozen and will eventually be deprecated. New code should use "paste.edit" instead.

func (*Conn) PasteQuery 

func (c *Conn) PasteQuery(
	req *requests.PasteQueryRequest,
) (responses.PasteQueryResponse, error)

PasteQuery calls the paste.query endpoint. Deprecated: This method is frozen and will eventually be deprecated. New code should use "paste.search" instead.

func (*Conn) PasteSearch added in v0.3.0 

func (c *Conn) PasteSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

PasteSearch performs a call to paste.search

func (*Conn) PhrictionContentSearch added in v0.3.0 

func (c *Conn) PhrictionContentSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

PhrictionContentSearch performs a call to phriction.content.search

func (*Conn) PhrictionDocumentSearch added in v0.3.0 

func (c *Conn) PhrictionDocumentSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

PhrictionDocumentSearch performs a call to phriction.document.search

func (*Conn) PhrictionInfo added in v0.3.0 

func (c *Conn) PhrictionInfo(
	req requests.PhrictionInfoRequest,
) (*responses.PhrictionInfoResponse, error)

PhrictionInfo performs a call to phriction.info Deprecated: This method is frozen and will eventually be deprecated. New code should use "phriction.document.search" instead.

func (*Conn) PhurlsSearch added in v0.3.0 

func (c *Conn) PhurlsSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

PhurlsSearch performs a call to phurls.search

func (*Conn) ProjectColumnSearch added in v0.3.0 

func (c *Conn) ProjectColumnSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

func (*Conn) ProjectEdit added in v0.3.0 

func (c *Conn) ProjectEdit(req requests.EditRequest) (*responses.EditResponse, error)

func (*Conn) ProjectQuery 

func (c *Conn) ProjectQuery(
	req requests.ProjectQueryRequest,
) (*responses.ProjectQueryResponse, error)

ProjectQuery performs a call to project.query.

func (*Conn) ProjectSearch added in v0.3.0 

func (c *Conn) ProjectSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

ProjectSearch performs a call to project.search

func (*Conn) RemarkupProcess added in v0.3.0 

func (c *Conn) RemarkupProcess(
	req requests.RemarkupProcessRequest,
) (*responses.RemarkupProcessResponse, error)

RemarkupProcess performs a call to remarkup.process

func (*Conn) RepositoryQuery 

func (c *Conn) RepositoryQuery(
	req requests.RepositoryQueryRequest,
) (*responses.RepositoryQueryResponse, error)

RepositoryQuery performs a call to repository.query. Deprecated: This method is frozen and will eventually be deprecated. New code should use "diffusion.repository.search" instead.

func (*Conn) TransactionSearch added in v0.3.0 

func (c *Conn) TransactionSearch(req requests.TransactionSearchRequest) (*responses.TransactionSearchResponse, error)

TransactionSearch performs a call to transaction.search.

func (*Conn) UserEdit added in v0.3.0 

func (c *Conn) UserEdit(req requests.EditRequest) (*responses.EditResponse, error)

UserEdit performs a call to user.edit

func (*Conn) UserQuery added in v0.3.0 

func (c *Conn) UserQuery(
	req requests.UserQueryRequest,
) (*responses.UserQueryResponse, error)

UserQuery performs a call to user.query. Deprecated: This method is frozen and will eventually be deprecated. New code should use "user.search" instead.

func (*Conn) UserSearch added in v0.3.0 

func (c *Conn) UserSearch(req requests.SearchRequest) (*responses.SearchResponse, error)

UserSearch performs a call to user.search

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.

Source Files

View all Source files

Directories

Path Synopsis
test
server

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.