// Copyright 2017 - 2019 Fabian Wenzelmann // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // Package etherpadlite provides an interface for Etherpad-Lite's HTTP API // written entirely in Go. // The API documentation can be found at https://github.com/ether/etherpad-lite/wiki/HTTP-API. // To use it create an instance of etherpadlite.EtherpadLite and call the // API methods on it, for example CreatePad(nil, padID, text). // If a parameter is optional, like text is in createPad, // simply set the value to etherpadlite.OptionalParam. // If there is a parameter with a default value, like copyPad(sourceID, destinationID[, force=false]), // setting the parameter to OptionalParam will set the value to the default value. // // All methods return a Response and an error (!= nil if something went wrong). // The first argument of all methods is always a Context ctx. If set to a non-nil // context the method will return nil and an error != nil when the // context gets cancelled. // If you don't want to use any context stuff just set it to nil. // This is however not the best practice to set the context, better set it to // context.Background or context.TODO if you don't want to use the context. // // It is safe to call the API methods simultaneously from multiple goroutines. // // I didn't document the methods since they're documented very well on the // etherpad homepage: https://etherpad.org/doc/v1.7.5/#index_http_api package etherpadlite import ( "context" "encoding/json" "fmt" "net/http" "net/url" ) // optionalParamType is an unexported type to identify an optional parameter // we don't want to use. type optionalParamType int const ( // CurrentVersion is the default version to use. CurrentVersion = "1.2.13" // OptionalParam is a constant used to identify an optional parameter we don't // want to use. OptionalParam optionalParamType = 0 ) // EtherpadLite is a struct that is used to connect to the etherpadlite API. type EtherpadLite struct { // APIVersion is the api version to use. It defaults to "1.2.13" in // NewEtherpadLite. APIVersion string // BaseParams are the parameter that are required in each request, i.e. // will be sent in each request. // The entry BaseParams["apikey"] = YOUR-API-KEY // should always be present. // NewEtherpadLite will take care of this. BaseParams map[string]interface{} // BaseURL is the URL pointing to the API of your pad, i.e. // http://pad.domain/api // It defaults to http://localhost:9001/api in NewEtherpadLite. BaseURL string // Client is used to send the GET requests to the API. // Set the values as required. // It defaults to the http.DefaultClient in NewEtherpadLite. Client *http.Client // RaiseEtherpadErrors specifies if errors returned by etherpad should be // returned as errors in Go or should be handled by the caller by checking // the response code. // It defaults to False. // By setting it to true the calls to all functions will return an error // for all responses with Response.Code != EverythingOk. // In this case an instance of EtherpadError is raised. RaiseEtherpadErrors bool } // NewEtherpadLite creates a new EtherpadLite instance given the // mandatory apiKey. // Create a new instance with this method and then configure it if you must. func NewEtherpadLite(apiKey string) *EtherpadLite { baseParams := make(map[string]interface{}) baseParams["apikey"] = apiKey client := http.DefaultClient return &EtherpadLite{APIVersion: CurrentVersion, BaseParams: baseParams, BaseURL: "http://localhost:9001/api", Client: client, RaiseEtherpadErrors: false, } } // ReturnCode is the code return by the etherpad API, see API documentation // for more details. type ReturnCode int const ( EverythingOk ReturnCode = iota WrongParameters InternalError NoSuchFunction WrongAPIKey ) func (c ReturnCode) String() string { switch c { case EverythingOk: return "0 everything ok" case WrongParameters: return "1 wrong parameters" case InternalError: return "2 internal error" case NoSuchFunction: return "3 no such function" case WrongAPIKey: return "4 no or wrong API Key" default: return fmt.Sprintf("%d unknown return code", int(c)) } } // Response is the response from the etherpad API. // See https://github.com/ether/etherpad-lite/wiki/HTTP-API type Response struct { Code ReturnCode Message string Data map[string]interface{} } // EtherpadError is an error returned by all methods if // EtherpadLite.RaiseEtherpadErrors is true. It reports any internal error // returned by calling the HTTP API of etherpad, signaling that the ReturnCode // is not EverythingOk. type EtherpadError struct { code ReturnCode message string } // NewEtherpadError returns a new EtherpadError. // The code should be != EverythingOk and the message is the error message // returned by the HTTP API. func NewEtherpadError(code ReturnCode, message string) EtherpadError { return EtherpadError{code: code, message: message} } // Error returns the error as a string. func (e EtherpadError) Error() string { codeStr := e.code.String() return fmt.Sprintf("%s: %s", codeStr, e.message) } // sendRequest is the function doing most of the work by sending the real // request. It will encode the BaseParams and params into URL queries and // do the http GET. // It decodes the JSON result and returns the decoded version. // If ctx != nil the method will be cancelled once ctx gets cancelled. // Note that ctx = nil, should not be used according to the documentation, // but we allow it since it's much easier. // Instead we could always use context.Background(). func (pad *EtherpadLite) sendRequest(ctx context.Context, path string, params map[string]interface{}) (*Response, error) { getURL, err := url.Parse(fmt.Sprintf("%s/%s/%s", pad.BaseURL, pad.APIVersion, path)) if err != nil { return nil, err } parameters := url.Values{} for key, value := range pad.BaseParams { parameters.Add(key, fmt.Sprintf("%v", value)) } for key, value := range params { parameters.Add(key, fmt.Sprintf("%v", value)) } getURL.RawQuery = parameters.Encode() req, reqErr := http.NewRequest("GET", getURL.String(), nil) if reqErr != nil { return nil, reqErr } if ctx != nil { req = req.WithContext(ctx) } resp, doErr := pad.Client.Do(req) if resp != nil { defer resp.Body.Close() } if doErr != nil { return nil, doErr } var padResponse Response if jsonErr := json.NewDecoder(resp.Body).Decode(&padResponse); jsonErr != nil { return nil, jsonErr } // check how to handle response errors // and if we have to care about them what to do about it if pad.RaiseEtherpadErrors && padResponse.Code != EverythingOk { return &padResponse, NewEtherpadError(padResponse.Code, padResponse.Message) } return &padResponse, nil } // Groups func (pad *EtherpadLite) CreateGroup(ctx context.Context) (*Response, error) { return pad.sendRequest(ctx, "createGroup", nil) } func (pad *EtherpadLite) CreateGroupIfNotExistsFor(ctx context.Context, groupMapper interface{}) (*Response, error) { return pad.sendRequest(ctx, "createGroupIfNotExistsFor", map[string]interface{}{"groupMapper": groupMapper}) } func (pad *EtherpadLite) DeleteGroup(ctx context.Context, groupID interface{}) (*Response, error) { return pad.sendRequest(ctx, "deleteGroup", map[string]interface{}{"groupID": groupID}) } func (pad *EtherpadLite) ListPads(ctx context.Context, groupID interface{}) (*Response, error) { return pad.sendRequest(ctx, "listPads", map[string]interface{}{"groupID": groupID}) } func (pad *EtherpadLite) CreateGroupPad(ctx context.Context, groupID, padName, text interface{}) (*Response, error) { params := map[string]interface{}{"groupID": groupID, "padName": padName} if text != OptionalParam { params["text"] = text } return pad.sendRequest(ctx, "createGroupPad", params) } func (pad *EtherpadLite) ListAllGroups(ctx context.Context) (*Response, error) { return pad.sendRequest(ctx, "listAllGroups", nil) } // Author func (pad *EtherpadLite) CreateAuthor(ctx context.Context, name interface{}) (*Response, error) { params := make(map[string]interface{}) if name != OptionalParam { params["name"] = name } return pad.sendRequest(ctx, "createAuthor", params) } func (pad *EtherpadLite) CreateAuthorIfNotExistsFor(ctx context.Context, authorMapper, name interface{}) (*Response, error) { params := map[string]interface{}{"authorMapper": authorMapper} if name != OptionalParam { params["name"] = name } return pad.sendRequest(ctx, "createAuthorIfNotExistsFor", params) } func (pad *EtherpadLite) ListPadsOfAuthor(ctx context.Context, authorID interface{}) (*Response, error) { return pad.sendRequest(ctx, "listPadsOfAuthor", map[string]interface{}{"authorID": authorID}) } func (pad *EtherpadLite) GetAuthorName(ctx context.Context, authorID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getAuthorName", map[string]interface{}{"authorID": authorID}) } // Session func (pad *EtherpadLite) CreateSession(ctx context.Context, groupID, authorID, validUntil interface{}) (*Response, error) { return pad.sendRequest(ctx, "createSession", map[string]interface{}{"groupID": groupID, "authorID": authorID, "validUntil": validUntil}) } func (pad *EtherpadLite) DeleteSession(ctx context.Context, sessionID interface{}) (*Response, error) { return pad.sendRequest(ctx, "deleteSession", map[string]interface{}{"sessionID": sessionID}) } func (pad *EtherpadLite) GetSessionInfo(ctx context.Context, sessionID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getSessionInfo", map[string]interface{}{"sessionID": sessionID}) } func (pad *EtherpadLite) ListSessionsOfGroup(ctx context.Context, groupID interface{}) (*Response, error) { return pad.sendRequest(ctx, "listSessionsOfGroup", map[string]interface{}{"groupID": groupID}) } func (pad *EtherpadLite) ListSessionsOfAuthor(ctx context.Context, authorID interface{}) (*Response, error) { return pad.sendRequest(ctx, "listSessionsOfAuthor", map[string]interface{}{"authorID": authorID}) } // Pad Content func (pad *EtherpadLite) GetText(ctx context.Context, padID, rev interface{}) (*Response, error) { params := map[string]interface{}{"padID": padID} if rev != OptionalParam { params["rev"] = rev } return pad.sendRequest(ctx, "getText", params) } func (pad *EtherpadLite) SetText(ctx context.Context, padID, text interface{}) (*Response, error) { return pad.sendRequest(ctx, "setText", map[string]interface{}{"padID": padID, "text": text}) } func (pad *EtherpadLite) AppendText(ctx context.Context, padID, text interface{}) (*Response, error) { return pad.sendRequest(ctx, "appendText", map[string]interface{}{"padID": padID, "text": text}) } func (pad *EtherpadLite) GetHTML(ctx context.Context, padID, rev interface{}) (*Response, error) { params := map[string]interface{}{"padID": padID} if rev != OptionalParam { params["rev"] = rev } return pad.sendRequest(ctx, "getHTML", params) } func (pad *EtherpadLite) SetHTML(ctx context.Context, padID, html interface{}) (*Response, error) { return pad.sendRequest(ctx, "setHTML", map[string]interface{}{"padID": padID, "html": html}) } func (pad *EtherpadLite) GetAttributePool(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getAttributePool", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) GetRevisionChangeset(ctx context.Context, padID, rev interface{}) (*Response, error) { params := map[string]interface{}{"padID": padID} if rev != OptionalParam { params["rev"] = rev } return pad.sendRequest(ctx, "getRevisionChangeset", params) } func (pad *EtherpadLite) CreateDiffHTML(ctx context.Context, padID, startRev, endRev interface{}) (*Response, error) { return pad.sendRequest(ctx, "createDiffHTML", map[string]interface{}{ "padID": padID, "startRev": startRev, "endRev": endRev, }) } func (pad *EtherpadLite) RestoreRevision(ctx context.Context, padId, rev interface{}) (*Response, error) { return pad.sendRequest(ctx, "restoreRevision", map[string]interface{}{"padId": padId, "rev": rev}) } // Chat func (pad *EtherpadLite) GetChatHistory(ctx context.Context, padID, start, end interface{}) (*Response, error) { params := map[string]interface{}{"padID": padID} // actually here both start and end must be != OptionalParam, not just one // of them. But we let the user read the docs, errors here are only for things // that really go wrong if start != OptionalParam { params["start"] = start } if end != OptionalParam { params["end"] = end } return pad.sendRequest(ctx, "getChatHistory", params) } func (pad *EtherpadLite) GetChatHead(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getChatHead", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) appendChatMessage(ctx context.Context, padID, text, authorID, time interface{}) (*Response, error) { params := map[string]interface{}{"padID": padID, "text": text, "authorID": authorID} if time != OptionalParam { params["time"] = time } return pad.sendRequest(ctx, "appendChatMessage", params) } // Pad func (pad *EtherpadLite) CreatePad(ctx context.Context, padID, text interface{}) (*Response, error) { params := map[string]interface{}{"padID": padID} if text != OptionalParam { params["text"] = text } return pad.sendRequest(ctx, "createPad", params) } func (pad *EtherpadLite) GetRevisionsCount(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getRevisionsCount", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) GetSavedRevisionsCount(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getSavedRevisionsCount", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) ListSavedRevisions(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "listSavedRevisions", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) SaveRevision(ctx context.Context, padID, rev interface{}) (*Response, error) { params := map[string]interface{}{"padID": padID} if rev != OptionalParam { params["rev"] = rev } return pad.sendRequest(ctx, "saveRevision", params) } func (pad *EtherpadLite) PadUsersCount(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "padUsersCount", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) PadUsers(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "padUsers", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) DeletePad(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "deletePad", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) CopyPad(ctx context.Context, sourceID, destinationID, force interface{}) (*Response, error) { params := map[string]interface{}{"sourceID": sourceID, "destinationID": destinationID} if force == OptionalParam { params["force"] = false } else { params["force"] = force } return pad.sendRequest(ctx, "copyPad", params) } func (pad *EtherpadLite) MovePad(ctx context.Context, sourceID, destinationID, force interface{}) (*Response, error) { params := map[string]interface{}{"sourceID": sourceID, "destinationID": destinationID} if force == OptionalParam { params["force"] = false } else { params["force"] = force } return pad.sendRequest(ctx, "movePad", params) } func (pad *EtherpadLite) GetReadOnlyID(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getReadOnlyID", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) GetPadID(ctx context.Context, readOnlyID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getPadID", map[string]interface{}{"readOnlyID": readOnlyID}) } func (pad *EtherpadLite) SetPublicStatus(ctx context.Context, padID, publicStatus interface{}) (*Response, error) { return pad.sendRequest(ctx, "setPublicStatus", map[string]interface{}{"padID": padID, "publicStatus": publicStatus}) } func (pad *EtherpadLite) GetPublicStatus(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getPublicStatus", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) SetPassword(ctx context.Context, padID, password interface{}) (*Response, error) { return pad.sendRequest(ctx, "setPassword", map[string]interface{}{"padID": padID, "password": password}) } func (pad *EtherpadLite) IsPasswordProtected(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "isPasswordProtected", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) ListAuthorsOfPad(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "listAuthorsOfPad", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) GetLastEdited(ctx context.Context, padID interface{}) (*Response, error) { return pad.sendRequest(ctx, "getLastEdited", map[string]interface{}{"padID": padID}) } func (pad *EtherpadLite) SendClientsMessage(ctx context.Context, padID, msg interface{}) (*Response, error) { return pad.sendRequest(ctx, "sendClientsMessage", map[string]interface{}{"padID": padID, "msg": msg}) } func (pad *EtherpadLite) CheckToken(ctx context.Context) (*Response, error) { return pad.sendRequest(ctx, "checkToken", nil) } // Pads func (pad *EtherpadLite) ListAllPads(ctx context.Context) (*Response, error) { return pad.sendRequest(ctx, "listAllPads", nil) }