Documentation ¶
Overview ¶
This package was generated from the schema defined at /references/notify/v1/api.json 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 <rootUrl>/references/notify/v1/api.json together with the input and output schemas it references,
Index ¶
- 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) Heartbeat() error
- func (notify *Notify) Lbheartbeat() 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) Matrix(payload *SendMatrixNoticeRequest) error
- func (notify *Notify) Ping() error
- func (notify *Notify) Pulse(payload *PostPulseMessageRequest) error
- func (notify *Notify) Slack(payload *SendSlackMessage) error
- func (notify *Notify) Version() error
- type PostPulseMessageRequest
- type SendEmailRequest
- type SendMatrixNoticeRequest
- type SendSlackMessage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Link ¶
type Link struct { // Where the link should point to. // // Min length: 1 // Max length: 1024 Href string `json:"href"` // Text to display on link. // // Min length: 1 // Max length: 40 Text string `json:"text"` }
Optional link that can be added as a button to the email.
type ListOfNotificationAdresses ¶
type ListOfNotificationAdresses struct { 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. ContinuationToken string `json:"continuationToken,omitempty"` }
List of notification addresses.
type NotificationTypeAndAddress ¶
type NotificationTypeAndAddress struct { NotificationAddress string `json:"notificationAddress"` // Possible values: // * "email" // * "pulse" // * "matrix-room" // * "slack-channel" NotificationType string `json:"notificationType"` }
Type of notification and its corresponding address.
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. 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) Heartbeat ¶ added in v44.8.2
Respond with a service heartbeat.
This endpoint is used to check on backing services this service depends on.
See #heartbeat
func (*Notify) Lbheartbeat ¶ added in v44.8.0
Respond without doing anything. This endpoint is used to check that the service is up.
See #lbheartbeat
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) Matrix ¶
func (notify *Notify) Matrix(payload *SendMatrixNoticeRequest) error
Stability: *** EXPERIMENTAL ***
Post a message to a room in Matrix. Optionally includes formatted message.
The `roomId` in the scopes is a fully formed `roomId` with leading `!` such as `!foo:bar.com`.
Note that the matrix client used by taskcluster must be invited to a room before it can post there!
Required scopes:
notify:matrix-room:<roomId>
See #matrix
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
func (*Notify) Slack ¶
func (notify *Notify) Slack(payload *SendSlackMessage) error
Stability: *** EXPERIMENTAL ***
Post a message to a Slack channel.
The `channelId` in the scopes is a Slack channel ID, starting with a capital C.
The Slack app can post into public channels by default but will need to be added to private channels before it can post messages there.
Required scopes:
notify:slack-channel:<channelId>
See #slack
func (*Notify) Version ¶ added in v44.8.0
Respond with the JSON version object. https://github.com/mozilla-services/Dockerflow/blob/main/docs/version_object.md
See #version
type PostPulseMessageRequest ¶
type PostPulseMessageRequest struct { // Pulse message to send as plain text. // // Additional properties allowed Message json.RawMessage `json:"message"` // Routing-key to use when posting the message. // // Max length: 255 RoutingKey string `json:"routingKey"` }
Request to post a message on pulse.
type SendEmailRequest ¶
type SendEmailRequest struct { // E-mail address to which the message should be sent 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 Content string `json:"content"` // Optional link that can be added as a button to the email. Link Link `json:"link,omitempty"` // Reply-to e-mail (this property is optional) ReplyTo string `json:"replyTo,omitempty"` // Subject line of the e-mail, this is plain-text // // Min length: 1 // Max length: 255 Subject string `json:"subject"` // E-mail html template used to format your content. // // Possible values: // * "simple" // * "fullscreen" // // Default: "simple" Template string `json:"template,omitempty"` }
Request to send an email
type SendMatrixNoticeRequest ¶
type SendMatrixNoticeRequest struct { // Unformatted text that will be displayed in the room if you do not // specify `formattedBody` or if a user's client can not render the format. Body string `json:"body"` // The format for `formattedBody`. For instance, `org.matrix.custom.html` Format string `json:"format,omitempty"` // Text that will be rendered by matrix clients that support the given // format in that format. For instance, `<h1>Header Text</h1>`. FormattedBody string `json:"formattedBody,omitempty"` // Which of the `m.room.message` msgtypes to use. At the moment only the // types that take `body`/`format`/`formattedBody` are supported. // // Possible values: // * "m.notice" // * "m.text" // * "m.emote" // // Default: "m.notice" Msgtype string `json:"msgtype,omitempty"` // The fully qualified room name, such as `!whDRjjSmICCgrhFHsQ:mozilla.org` // If you are using riot, you can find this under the advanced settings for a room. RoomID string `json:"roomId"` }
Request to send a Matrix notice. Many of these fields are better understood by checking the matrix spec itself. The precise definitions of these fields is beyond the scope of this document.
type SendSlackMessage ¶
type SendSlackMessage struct { // An array of Slack attachments. See https://api.slack.com/messaging/composing/layouts#attachments. Attachments []interface{} `json:"attachments,omitempty"` // An array of Slack layout blocks. See https://api.slack.com/reference/block-kit/blocks. Blocks []interface{} `json:"blocks,omitempty"` // The unique Slack channel ID, such as `C123456GZ`. // In the app, this is the last section of the 'copy link' URL for a channel. ChannelID string `json:"channelId"` // The main message text. If no blocks are included, this is used as the // message text, otherwise this is used as alternative text and the blocks // are used. Text string `json:"text"` }
Request to send a message to a Slack channel. The most interesting field in this request is the `blocks` field which allows you to specify advanced display layout for messages. This is best understood via the Slack API documentation.