Documentation ¶
Overview ¶
The notification service listens for tasks with associated notifications and handles requests to send emails and post pulse messages.
See:
How to use this package ¶
First create a Notify object:
notify := tcnotify.New(nil)
and then call one or more of notify's methods, e.g.:
err := notify.Ping(.....)
handling any errors...
if err != nil { // handle error... }
Taskcluster Schema ¶
The source code of this go package was auto-generated from the API definition at https://taskcluster-staging.net/references/notify/v1/api.json together with the input and output schemas it references, downloaded on Thu, 27 Jun 2019 at 07:22:00 UTC. The code was generated by https://github.com/taskcluster/taskcluster-client-go/blob/master/build.sh.
Index ¶
- type ChannelMessage
- type Link
- type ListOfNotificationAdresses
- type NotificationTypeAndAddress
- type Notify
- func (notify *Notify) AddDenylistAddress(payload *NotificationTypeAndAddress) error
- func (notify *Notify) DeleteDenylistAddress(payload *NotificationTypeAndAddress) error
- func (notify *Notify) Email(payload *SendEmailRequest) error
- func (notify *Notify) Irc(payload *PostIRCMessageRequest) error
- func (notify *Notify) ListDenylist(continuationToken, limit string) (*ListOfNotificationAdresses, error)
- func (notify *Notify) ListDenylist_SignedURL(continuationToken, limit string, duration time.Duration) (*url.URL, error)
- func (notify *Notify) Ping() error
- func (notify *Notify) Pulse(payload *PostPulseMessageRequest) error
- type PostIRCMessageRequest
- type PostPulseMessageRequest
- type PrivateMessage
- type SendEmailRequest
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ChannelMessage ¶
type ChannelMessage struct { // Channel to post the message in. // // Syntax: ^[#&][^ ,\u0007]{1,199}$ // Min length: 1 // // See https://taskcluster-staging.net/schemas/notify/v1/irc-request.json#/oneOf[0]/properties/channel Channel string `json:"channel"` // IRC message to send as plain text. // // Min length: 1 // Max length: 510 // // See https://taskcluster-staging.net/schemas/notify/v1/irc-request.json#/definitions/message Message string `json:"message"` }
Request to post a message on IRC.
See https://taskcluster-staging.net/schemas/notify/v1/irc-request.json#/oneOf[0]
type Link ¶
type Link struct { // Where the link should point to. // // Min length: 1 // Max length: 1024 // // See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#/properties/link/properties/href Href string `json:"href"` // Text to display on link. // // Min length: 1 // Max length: 40 // // See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#/properties/link/properties/text Text string `json:"text"` }
Optional link that can be added as a button to the email.
See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#/properties/link
type ListOfNotificationAdresses ¶
type ListOfNotificationAdresses struct { // See https://taskcluster-staging.net/schemas/notify/v1/notification-address-list.json#/properties/addresses Addresses []NotificationTypeAndAddress `json:"addresses"` // A continuation token is returned if there are more results than listed // here. You can optionally provide the token in the request payload to // load the additional results. // // See https://taskcluster-staging.net/schemas/notify/v1/notification-address-list.json#/properties/continuationToken ContinuationToken string `json:"continuationToken,omitempty"` }
List of notification addresses.
See https://taskcluster-staging.net/schemas/notify/v1/notification-address-list.json#
type NotificationTypeAndAddress ¶
type NotificationTypeAndAddress struct { // See https://taskcluster-staging.net/schemas/notify/v1/notification-address.json#/properties/notificationAddress NotificationAddress string `json:"notificationAddress"` // Possible values: // * "email" // * "pulse" // * "irc-user" // * "irc-channel" // // See https://taskcluster-staging.net/schemas/notify/v1/notification-address.json#/properties/notificationType NotificationType string `json:"notificationType"` }
Type of notification and its corresponding address.
See https://taskcluster-staging.net/schemas/notify/v1/notification-address.json#
type Notify ¶
func New ¶
func New(credentials *tcclient.Credentials, rootURL string) *Notify
New returns a Notify client, configured to run against production. Pass in nil credentials to create a client without authentication. The returned client is mutable, so returned settings can be altered.
notify := tcnotify.New( nil, // client without authentication "http://localhost:1234/my/taskcluster", // taskcluster hosted at this root URL on local machine ) err := notify.Ping(.....) // for example, call the Ping(.....) API endpoint (described further down)... if err != nil { // handle errors... }
func NewFromEnv ¶
func NewFromEnv() *Notify
NewFromEnv returns a *Notify configured from environment variables.
The root URL is taken from TASKCLUSTER_PROXY_URL if set to a non-empty string, otherwise from TASKCLUSTER_ROOT_URL if set, otherwise the empty string.
The credentials are taken from environment variables:
TASKCLUSTER_CLIENT_ID TASKCLUSTER_ACCESS_TOKEN TASKCLUSTER_CERTIFICATE
If TASKCLUSTER_CLIENT_ID is empty/unset, authentication will be disabled.
func (*Notify) AddDenylistAddress ¶
func (notify *Notify) AddDenylistAddress(payload *NotificationTypeAndAddress) error
Stability: *** EXPERIMENTAL ***
Add the given address to the notification denylist. The address can be of either of the three supported address type namely pulse, email or IRC(user or channel). Addresses in the denylist will be ignored by the notification service.
Required scopes:
notify:manage-denylist
See #addDenylistAddress
func (*Notify) DeleteDenylistAddress ¶
func (notify *Notify) DeleteDenylistAddress(payload *NotificationTypeAndAddress) error
Stability: *** EXPERIMENTAL ***
Delete the specified address from the notification denylist.
Required scopes:
notify:manage-denylist
See #deleteDenylistAddress
func (*Notify) Email ¶
func (notify *Notify) Email(payload *SendEmailRequest) error
Stability: *** EXPERIMENTAL ***
Send an email to `address`. The content is markdown and will be rendered to HTML, but both the HTML and raw markdown text will be sent in the email. If a link is included, it will be rendered to a nice button in the HTML version of the email
Required scopes:
notify:email:<address>
See #email
func (*Notify) Irc ¶
func (notify *Notify) Irc(payload *PostIRCMessageRequest) error
Stability: *** EXPERIMENTAL ***
Post a message on IRC to a specific channel or user, or a specific user on a specific channel.
Success of this API method does not imply the message was successfully posted. This API method merely inserts the IRC message into a queue that will be processed by a background process. This allows us to re-send the message in face of connection issues.
However, if the user isn't online the message will be dropped without error. We maybe improve this behavior in the future. For now just keep in mind that IRC is a best-effort service.
Required scopes:
If channelRequest: notify:irc-channel:<channel>
See #irc
func (*Notify) ListDenylist ¶
func (notify *Notify) ListDenylist(continuationToken, limit string) (*ListOfNotificationAdresses, error)
Stability: *** EXPERIMENTAL ***
Lists all the denylisted addresses.
By default this end-point will try to return up to 1000 addresses in one request. But it **may return less**, even if more tasks are available. It may also return a `continuationToken` even though there are no more results. However, you can only be sure to have seen all results if you keep calling `list` with the last `continuationToken` until you get a result without a `continuationToken`.
If you are not interested in listing all the members at once, you may use the query-string option `limit` to return fewer.
Required scopes:
notify:manage-denylist
See #listDenylist
func (*Notify) ListDenylist_SignedURL ¶
func (notify *Notify) ListDenylist_SignedURL(continuationToken, limit string, duration time.Duration) (*url.URL, error)
Returns a signed URL for ListDenylist, valid for the specified duration.
Required scopes:
notify:manage-denylist
See ListDenylist for more details.
func (*Notify) Ping ¶
Respond without doing anything. This endpoint is used to check that the service is up.
See #ping
func (*Notify) Pulse ¶
func (notify *Notify) Pulse(payload *PostPulseMessageRequest) error
Stability: *** EXPERIMENTAL ***
Publish a message on pulse with the given `routingKey`.
Required scopes:
notify:pulse:<routingKey>
See #pulse
type PostIRCMessageRequest ¶
type PostIRCMessageRequest json.RawMessage
Request to post a message on IRC.
One of:
- ChannelMessage
- PrivateMessage
See https://taskcluster-staging.net/schemas/notify/v1/irc-request.json#
func (*PostIRCMessageRequest) MarshalJSON ¶
func (this *PostIRCMessageRequest) MarshalJSON() ([]byte, error)
MarshalJSON calls json.RawMessage method of the same name. Required since PostIRCMessageRequest is of type json.RawMessage...
func (*PostIRCMessageRequest) UnmarshalJSON ¶
func (this *PostIRCMessageRequest) UnmarshalJSON(data []byte) error
UnmarshalJSON is a copy of the json.RawMessage implementation.
type PostPulseMessageRequest ¶
type PostPulseMessageRequest struct { // Pulse message to send as plain text. // // Additional properties allowed // // See https://taskcluster-staging.net/schemas/notify/v1/pulse-request.json#/properties/message Message json.RawMessage `json:"message"` // Routing-key to use when posting the message. // // Max length: 255 // // See https://taskcluster-staging.net/schemas/notify/v1/pulse-request.json#/properties/routingKey RoutingKey string `json:"routingKey"` }
Request to post a message on pulse.
See https://taskcluster-staging.net/schemas/notify/v1/pulse-request.json#
type PrivateMessage ¶
type PrivateMessage struct { // IRC message to send as plain text. // // Min length: 1 // Max length: 510 // // See https://taskcluster-staging.net/schemas/notify/v1/irc-request.json#/definitions/message Message string `json:"message"` // User to post the message to. // // Syntax: ^[A-Za-z\[\]\\~_\^{|}][A-Za-z0-9\-\[\]\\~_\^{|}]{0,254}$ // Min length: 1 // Max length: 255 // // See https://taskcluster-staging.net/schemas/notify/v1/irc-request.json#/oneOf[1]/properties/user User string `json:"user"` }
Request to post a message on IRC.
See https://taskcluster-staging.net/schemas/notify/v1/irc-request.json#/oneOf[1]
type SendEmailRequest ¶
type SendEmailRequest struct { // E-mail address to which the message should be sent // // See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#/properties/address Address string `json:"address"` // Content of the e-mail as **markdown**, will be rendered to HTML before // the email is sent. Notice that markdown allows for a few HTML tags, but // won't allow inclusion of script tags and other unpleasantries. // // Min length: 1 // Max length: 102400 // // See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#/properties/content Content string `json:"content"` // Optional link that can be added as a button to the email. // // See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#/properties/link Link Link `json:"link,omitempty"` // Reply-to e-mail (this property is optional) // // See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#/properties/replyTo ReplyTo string `json:"replyTo,omitempty"` // Subject line of the e-mail, this is plain-text // // Min length: 1 // Max length: 255 // // See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#/properties/subject Subject string `json:"subject"` // E-mail html template used to format your content. // // Possible values: // * "simple" // * "fullscreen" // // Default: "simple" // // See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#/properties/template Template string `json:"template,omitempty"` }
Request to send an email
See https://taskcluster-staging.net/schemas/notify/v1/email-request.json#