jmap

package module
v0.0.0-...-6e1038e Latest Latest
Warning

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

 Go to latest Published: Sep 10, 2019 License: MIT Imports: 9 Imported by: 1

README

go-jmap Travis CI CodeCov Reference stability-experimental

JMAP Core client Go library.

License

The code is under MIT license.

Documentation strings for most of the protocol objects are taken from (or based on) contents of draft-ietf-jmap-core-17 and is subject to the IETF Trust Provisions. See https://trustee.ietf.org/trust-legal-provisions.html for details. See included draft-ietf-jmap-core-17.txt for related copyright notices.

Documentation

Overview

Package jmap implements JMAP Core protocol as defined in draft-ietf-jmap-core-17 (published March 2019).

Documentation strings for most of the protocol objects are taken from (or based on) contents of draft-ietf-jmap-core-17 and is subject to the IETF Trust Provisions. See https://trustee.ietf.org/trust-legal-provisions.html for details. See included draft-ietf-jmap-core-17.txt for related copyright notices.

Index

Constants

View Source 
const (
	// The ASCIINumeric collation is a simple collation intended for use
	// with arbitrary sized unsigned decimal integer numbers stored as octet
	// strings. US-ASCII digits (0x30 to 0x39) represent digits of the numbers.
	// Before converting from string to integer, the input string is truncated
	// at the first non-digit character. All input is valid; strings which do
	// not start with a digit represent positive infinity.
	//
	// Defined in RFC 4790.
	ASCIINumeric CollationAlgo = "i;ascii-numeric"

	// The ASCIICasemap collation is a simple collation which operates on
	// octet strings and treats US-ASCII letters case-insensitively. It provides
	// equality, substring and ordering operations. All input is valid. Note that
	// letters outside ASCII are not treated case- insensitively.
	//
	// Defined in RFC 4790.
	ASCIICasemap = "i;ascii-casemap"

	// The "i;unicode-casemap" collation is a simple collation which is
	// case-insensitive in its treatment of characters. It provides equality,
	// substring, and ordering operations. The validity test operation returns "valid"
	// for any input.
	//
	// This collation allows strings in arbitrary (and mixed) character sets,
	// as long as the character set for each string is identified and it is
	// possible to convert the string to Unicode. Strings which have an
	// unidentified character set and/or cannot be converted to Unicode are not
	// rejected, but are treated as binary.
	//
	// Defined in RFC 5051.
	UnicodeCasemap = "i;unicode-casemap"
)
View Source 
const CoreCapabilityName = "urn:ietf:params:jmap:core"

Variables

View Source 
var ErrInvalidId = errors.New("jmap: invalid id")
View Source 
var ErrNoCoreCapability = errors.New("jmap: urn:ietf:params:jmap:core capability object is missing")
View Source 
var ErrOutOfRange = errors.New("jmap: integer value is not within allowed range")

Functions

func RawUnmarshallers 

func RawUnmarshallers(methodNames []string) map[string]FuncArgsUnmarshal

RawUnmarshallers creates FuncArgsUnmarshal mapping functions that return json.RawMessage.

It allows to disable JSON decoding for Invocation arguments.

func UnmarshalMethodErrorArgs 

func UnmarshalMethodErrorArgs(args json.RawMessage) (interface{}, error)

Types

type Account 

type Account struct {
	// A user-friendly string to show when presenting content from this
	// account, e.g. the email address representing the owner of the account.
	Name string `json:"name"`

	// This is true if the account belongs to the authenticated user, rather
	// than a group account or a personal account of another user that has been
	// shared with them.
	IsPersonal bool `json:"isPersonal"`

	// This is true if the entire account is read-only.
	IsReadOnly bool `json:"isReadOnly"`

	// The set of capability URIs for the methods supported in this account.
	// Each key is a URI for a capability that has methods you can use with
	// this account. The value for each of these keys is an object with further
	// information about the account’s permissions and restrictions with
	// respect to this capability, as defined in the capability’s
	// specification.
	Capabilities map[string]json.RawMessage `json:"accountCapabilities"`
}

An account is a collection of data. A single account may contain an arbitrary set of data types, for example a collection of mail, contacts and calendars.

See draft-ietf-jmap-core-17, section 1.6.2 for details. The documentation is taked from draft-ietf-jmap-core-17, section 2.

type BlobInfo 

type BlobInfo struct {
	// The id of the account used for the call.
	AccountID ID `json:"accountId"`

	// The id representing the binary data uploaded. The data for this id is
	// immutable. The id only refers to the binary data, not any metadata.
	BlobID ID `json:"blobId"`

	// The media type of the file (as specified in RFC 6838, section 4.2) as
	// set in the Content-Type header of the upload HTTP request.
	Type string `json:"type"`

	// The size of the file in octets.
	Size UnsignedInt `json:"size"`
}

BlobInfo is the object returned in response to blob upload.

type CollationAlgo 

type CollationAlgo string

type CoreCapability 

type CoreCapability struct {
	// The maximum file size, in octets, that the server will accept for a
	// single file upload (for any purpose).
	MaxSizeUpload UnsignedInt `json:"maxSizeUpload"`

	// The maximum number of concurrent requests the server will accept to the
	// upload endpoint.
	MaxConcurrentUpload UnsignedInt `json:"maxConcurrentUpload"`

	// The maximum size, in octets, that the server will accept for a single
	// request to the API endpoint.
	MaxSizeRequest UnsignedInt `json:"maxSizeRequest"`

	// The maximum number of concurrent requests the server will accept to the
	// API endpoint.
	MaxConcurrentRequests UnsignedInt `json:"maxConcurrentRequests"`

	// The maximum number of method calls the server will accept in a single
	// request to the API endpoint.
	MaxCallsInRequest UnsignedInt `json:"maxCallsInRequest"`

	// The maximum number of objects that the client may request in a single
	// /get type method call.
	MaxObjectsInGet UnsignedInt `json:"maxObjectsInGet"`

	// The maximum number of objects the client may send to create, update or
	// destroy in a single /set type method call. This is the combined total, e.g.
	// if the maximum is 10 you could not create 7 objects and destroy 6, as this
	// would be 13 actions, which exceeds the limit.
	MaxObjectsInSet UnsignedInt `json:"maxObjectsInSet"`

	// A list of identifiers for algorithms registered in the collation
	// registry defined in RFC 4790 that the server supports for sorting
	// when querying records.
	CollationAlgorithms []CollationAlgo `json:"collationAlgorithms"`
}

type Date 

type Date time.Time

Date is a time.Time that is serialized to JSON in RFC 3339 format (without the fractional part).

func (Date) MarshalText 

func (d Date) MarshalText() ([]byte, error)

func (*Date) UnmarshalJSON 

func (d *Date) UnmarshalJSON(data []byte) error

type ErrorCode 

type ErrorCode string
const (
	// The accountId does not correspond to a valid account.
	CodeAccountNotFound ErrorCode = "accountNotFound"

	// The accountId given corresponds to a valid account, but the account does
	// not support this method or data type.
	CodeAccountNotSupportedByMethod ErrorCode = "accountNotSupportedByMethod"

	// This method call would modify state in an account that is read-only (as
	// returned on the corresponding Account object in the JMAP Session resource).
	CodeAccountReadOnly ErrorCode = "accountReadOnly"

	// An anchor argument was supplied, but it cannot be found in the results of
	// the query.
	CodeAnchorNotFound ErrorCode = "anchorNotFound"

	// The server forbids duplicates and the record already exists in the target
	// account. An existingId property of type Id MUST be included on the error
	// object with the id of the existing record.
	CodeAlreadyExists ErrorCode = "alreadyExists"

	// The server cannot calculate the changes from the state string given by the
	// client.
	CodeCannotCalculateChanges ErrorCode = "cannotCalculateChanges"

	// The action would violate an ACL or other permissions policy.
	CodeForbidden ErrorCode = "forbidden"

	// The fromAccountId does not correspond to a valid account.
	CodeFromAccountNotFound ErrorCode = "fromAccountNotFound"

	// The fromAccountId given corresponds to a valid account, but the account
	// does not support this data type.
	CodeFromAccountNotSupportedByMethod ErrorCode = "fromAccountNotSupportedByMethod"

	// One of the arguments is of the wrong type or otherwise invalid, or a
	// required argument is missing.
	CodeInvalidArguments ErrorCode = "invalidArguments"

	// The PatchObject given to update the record was not a valid patch.
	CodeInvalidPatch ErrorCode = "invalidPatch"

	// The record given is invalid.
	CodeInvalidProperties ErrorCode = "invalidProperties"

	// The id given cannot be found.
	CodeNotFound ErrorCode = "notFound"

	// The content type of the request was not application/json or the request did
	// not parse as I-JSON.
	CodeNotJSON ErrorCode = "notJSON"

	// The request parsed as JSON but did not match the type signature of the
	// Request object.
	CodeNotRequest ErrorCode = "notRequest"

	// The create would exceed a server-defined limit on the number or total size
	// of objects of this type.
	CodeOverQuota ErrorCode = "overQuota"

	// Too many objects of this type have been created recently, and a
	// server-defined rate limit has been reached. It may work if tried again
	// later.
	CodeRateLimit ErrorCode = "rateLimit"

	// The total number of actions exceeds the maximum number the server is
	// willing to process in a single method call.
	CodeRequestTooLarge ErrorCode = "requestTooLarge"

	// The method used a result reference for one of its arguments, but this
	// failed to resolve.
	CodeInvalidResultReference ErrorCode = "invalidResultReference"

	// An unexpected or unknown error occurred during the processing of the call.
	// The method call made no changes to the server's state.
	CodeServerFail ErrorCode = "serverFail"

	// Some, but not all expected changes described by the method occurred. The
	// client MUST re-synchronise impacted data to determine server state. Use of
	// this error is strongly discouraged.
	CodeServerPartialFail ErrorCode = "serverPartialFail"

	// Some internal server resource was temporarily unavailable. Attempting the
	// same operation later (perhaps after a backoff with a random factor) may
	// succeed.
	CodeServerUnavailable ErrorCode = "serverUnavailable"

	// This is a singleton type, so you cannot create another one or destroy the
	// existing one.
	CodeSingleton ErrorCode = "singleton"

	// An ifInState argument was supplied and it does not match the current state.
	CodeStateMismatch ErrorCode = "stateMismatch"

	// The action would result in an object that exceeds a server-defined limit
	// for the maximum size of a single object of this type.
	CodeTooLarge ErrorCode = "tooLarge"

	// There are more changes than the client's maxChanges argument.
	CodeTooManyChanges ErrorCode = "tooManyChanges"

	// The client included a capability in the "using" property of the request
	// that the server does not support.
	CodeUnknownCapability ErrorCode = "unknownCapability"

	// The server does not recognise this method name.
	CodeUnknownMethod ErrorCode = "unknownMethod"

	// The filter is syntactically valid, but the server cannot process it.
	CodeUnsupportedFilter ErrorCode = "unsupportedFilter"

	// The sort is syntactically valid, but includes a property the server does
	// not support sorting on, or a collation method it does not recognise.
	CodeUnsupportedSort ErrorCode = "unsupportedSort"

	// The client requested an object be both updated and destroyed in the same
	// /set request, and the server has decided to therefore ignore the update.
	CodeWillDestroy ErrorCode = "willDestroy"

	// The mailbox still has at least one child mailbox. The client MUST remove
	// these before it can delete the parent mailbox.
	CodeMailboxHasChild ErrorCode = "mailboxHasChild"

	// The mailbox has at least one message assigned to it and the
	// onDestroyRemoveMessages argument was false.
	CodeMailboxHasEmail ErrorCode = "mailboxHasEmail"

	// At least one blob id referenced in the object doesn't exist.
	CodeBlobNotFound ErrorCode = "blobNotFound"

	// The change to the email's keywords would exceed a server-defined maximum.
	CodeTooManyKeywords ErrorCode = "tooManyKeywords"

	// The change to the email's mailboxes would exceed a server-defined maximum.
	CodeTooManyMailboxes ErrorCode = "tooManyMailboxes"

	// The email to be sent is invalid in some way.
	CodeInvalidEmail ErrorCode = "invalidEmail"

	// The [RFC5321] envelope (supplied or generated) has more recipients than the
	// server allows.
	CodeTooManyRecipients ErrorCode = "tooManyRecipients"

	// The [RFC5321] envelope (supplied or generated) does not have any rcptTo
	// emails.
	CodeNoRecipients ErrorCode = "noRecipients"

	// The rcptTo property of the [RFC5321] envelope (supplied or generated)
	// contains at least one rcptTo value which is not a valid email for sending
	// to.
	CodeInvalidRecipients ErrorCode = "invalidRecipients"

	// The server does not permit the user to send an email with the [RFC5321]
	// envelope From.
	CodeForbiddenMailFrom ErrorCode = "forbiddenMailFrom"

	// The server does not permit the user to send an email with the [RFC5322]
	// From header field of the email to be sent.
	CodeForbiddenFrom ErrorCode = "forbiddenFrom"

	// The user does not have permission to send at all right now.
	CodeForbiddenToSend ErrorCode = "forbiddenToSend"
)
const ProblemPrefix ErrorCode = "urn:ietf:params:jmap:error:"

ProblemPrefix is added to corresponding error code when it is reported as a problem type in request-level error.

type FuncArgsUnmarshal 

type FuncArgsUnmarshal func(args json.RawMessage) (interface{}, error)

type ID 

type ID string

Id is a string of at least 1 and maximum 255 octets in size that must contain only characters from the "URL and Filename safe" Base 64 Alphabet (see section 5 of RFC 4648), excluding the pad character. This means the allowed charcters are ASCII alphanumeric characters, hypen and underscore.

func RandomID 

func RandomID() (ID, error)

RandomID generates random valid & safe Id object.

func (ID) MarshalText 

func (id ID) MarshalText() ([]byte, error)

func (ID) Safe 

func (id ID) Safe() bool

Safe function checks whether Id value is safe to use in filesystems, URLs, etc without escaping. In particular, for Id to be considered safe it: - Should not start with a dash - Should not start with digits - Should not contain only digits. - Should not be equal to "NIL".

JMAP specification requires that all used Ids are safe ("SHOULD").

func (*ID) UnmarshalJSON 

func (id *ID) UnmarshalJSON(data []byte) error

func (ID) Valid 

func (id ID) Valid() bool

Valid checks whether Id value is a valid identifier.

type Int 

type Int int64

Int type is an integer in the range -2^53+1 <= value <= 2^53-1.

func (Int) MarshalJSON 

func (i Int) MarshalJSON() ([]byte, error)

func (*Int) UnmarshalJSON 

func (i *Int) UnmarshalJSON(data []byte) error

func (Int) Valid 

func (i Int) Valid() bool

Valid checks whether value Int is set to is within the allowed range.

type Invocation 

type Invocation struct {
	Name   string
	CallID string
	Args   interface{}
}

type MethodErrorArgs 

type MethodErrorArgs struct {
	Type ErrorCode `json:"type"`

	// All fields other than Type.
	Properties map[string]interface{}
}

The MethodError structure describes method-level error.

See section 3.5.2 of JMAP Core specification.

func (MethodErrorArgs) Error 

func (me MethodErrorArgs) Error() string

func (MethodErrorArgs) MarshalJSON 

func (me MethodErrorArgs) MarshalJSON() ([]byte, error)

func (*MethodErrorArgs) UnmarshalJSONArgs 

func (me *MethodErrorArgs) UnmarshalJSONArgs(data []byte) error

type Request 

type Request struct {
	// The set of capabilities the client wishes to use. The client may include
	// capability identifiers even if the method calls it makes do not utilise
	// those capabilities.
	Using []string `json:"using"`

	// An array of method calls to process on the server. The method calls will
	// be processed sequentially, in order.
	Calls []Invocation `json:"-"`

	// A map of (client-specified) creation id to the id the server assigned
	// when a record was successfully created. Can be nil.
	CreatedIDs map[ID]ID `json:"createdIds,omitempty"`
}

func (Request) MarshalJSON 

func (r Request) MarshalJSON() ([]byte, error)

func (*Request) Unmarshal 

func (r *Request) Unmarshal(data io.Reader, argsUnmarshallers map[string]FuncArgsUnmarshal) error

Unmarshal deserializes Request object from JSON, calling functions from invocationCtors to deserialize Invocation objects. Key is method name.

If error is returned, Request object is not changed.

type RequestError 

type RequestError struct {
	// A URI reference that identifies the problem type.
	Type ErrorCode `json:"type"`

	// A short, human-readable summary of the problem type.
	Title string `json:"title,omitempty"`

	// The HTTP status code.
	Status int `json:"status,omitempty"`

	// A human-readable explanation specific to this occurrence of the problem.
	Detail string `json:"detail,omitempty"`

	// A URI reference that identifies the specific occurrence of the problem.
	Instance string `json:"instance,omitempty"`

	// All other fields.
	Properties map[string]interface{} `json:"-"`
}

The RequestError structure is "problem details" object as defined by RFC 7807. Any fields except for Type can be empty.

Used for all problem types that don't have any custom fields. Currently: - urn:ietf:params:jmap:error:unknownCapability (ProblemUnknownCapability) - urn:ietf:params:jmap:error:notJSON (ProblemNotJSON) - urn:ietf:params:jmap:error:notRequest (ProblemNotRequest)

func (RequestError) Error 

func (re RequestError) Error() string

func (RequestError) MarshalJSON 

func (re RequestError) MarshalJSON() ([]byte, error)

func (*RequestError) UnmarshalJSON 

func (re *RequestError) UnmarshalJSON(data []byte) error

type Response 

type Response struct {
	// An array of responses, in the same format as the Calls on the
	// Request object. The output of the methods will be added to the
	// methodResponses array in the same order as the methods are processed.
	Responses []Invocation `json:"-"`

	// A map of (client-specified) creation id to the id the server assigned
	// when a record was successfully created.
	CreatedIDs map[ID]ID `json:"createdIds,omitempty"`

	// The current value of the “state” string on the JMAP Session object, as
	// described in section 2. Clients may use this to detect if this object
	// has changed and needs to be refetched.
	SessionState string `json:"sessionState"`
}

func (Response) MarshalJSON 

func (r Response) MarshalJSON() ([]byte, error)

func (*Response) Unmarshal 

func (r *Response) Unmarshal(data io.Reader, argsUnmarshallers map[string]FuncArgsUnmarshal) error

Unmarshal deserializes Response object from JSON, calling functions from invocationCtors to deserialize Invocation objects. Key is method name. Callback for error decoding is added to invocationCtors implicitly.

If error is returned, Response object is not changed.

type Session 

type Session struct {
	// An object specifying the capabilities of this server. Each key is a URI
	// for a capability supported by the server. The value for each of these
	// keys is an object with further information about the server’s
	// capabilities in relation to that capability.
	Capabilities map[string]json.RawMessage `json:"capabilities"`

	// Deserialized urn:ietf:params:jmap:core capability object.
	CoreCapability CoreCapability `json:"-"`

	// A map of account id to Account object for each account the user has
	// access to.
	Accounts map[ID]Account `json:"accounts"`

	// A map of capability URIs (as found in Capabilities) to the
	// account id to be considered the user’s main or default account for data
	// pertaining to that capability.
	PrimaryAccounts map[string]ID `json:"primaryAccounts"`

	// The username associated with the given credentials, or the empty string
	// if none.
	Username string `json:"username"`

	// The URL to use for JMAP API requests.
	APIURL string `json:"apiUrl"`

	// The URL endpoint to use when downloading files, in RFC 6570 URI
	// Template (level 1) format.
	DownloadURL string `json:"downloadUrl"`

	// The URL endpoint to use when uploading files, in RFC 6570 URI
	// Template (level 1) format.
	UploadURL string `json:"uploadUrl"`

	// The URL to connect to for push events, as described in section 7.3, in
	// RFC 6570 URI Template (level 1) format.
	EventSourceURL string `json:"eventSourceUrl"`

	// A string representing the state of this object on the server. If the
	// value of any other property on the session object changes, this string
	// will change.
	//
	// The current value is also returned on the API Response object, allowing
	// clients to quickly determine if the session information has changed
	// (e.g. an account has been added or removed) and so they need to refetch
	// the object.
	State string `json:"state"`
}

The Session object ... FIXME

The documentation is taked from draft-ietf-jmap-core-17, section 2.

func (*Session) UnmarshalJSON 

func (s *Session) UnmarshalJSON(data []byte) error

type UTCDate 

type UTCDate time.Time

Date is a time.Time that is serialized to JSON in RFC 3339 format (without the fractional part) in UTC timezone.

If UTCDate value is not in UTC, it will be converted to UTC during serialization.

func (UTCDate) MarshalText 

func (d UTCDate) MarshalText() ([]byte, error)

func (*UTCDate) UnmarshalJSON 

func (d *UTCDate) UnmarshalJSON(data []byte) error

type UnknownMethodError 

type UnknownMethodError struct {
	MethodName string
}

func (UnknownMethodError) Error 

func (ume UnknownMethodError) Error() string

type UnsignedInt 

type UnsignedInt uint64

UnsignedInt is an integer in the range 0 <= value <= 2^53-1.

func (UnsignedInt) MarshalJSON 

func (i UnsignedInt) MarshalJSON() ([]byte, error)

func (*UnsignedInt) UnmarshalJSON 

func (i *UnsignedInt) UnmarshalJSON(data []byte) error

func (UnsignedInt) Valid 

func (i UnsignedInt) Valid() bool

Valid checks whether value UnsignedInt is set to is within the allowed range.

Source Files

View all Source files

Directories

Path Synopsis
Package autodiscovery implements JMAP service autodiscovery mechanism described in section 2.2 of JMAP Core RFC.
 Package autodiscovery implements JMAP service autodiscovery mechanism described in section 2.2 of JMAP Core RFC.
The client package implements base wrappers for JMAP Core protocol client.
 The client package implements base wrappers for JMAP Core protocol client.

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.