diff --git a/README.md b/README.md index fa171af..5e232c4 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ A package to send messages to Microsoft Teams (channels) - [How to create a webhook URL (Connector)](#how-to-create-a-webhook-url-connector) - [Examples](#examples) - [Basic](#basic) + - [Set custom user agent](#set-custom-user-agent) - [Add an Action](#add-an-action) - [Disable webhook URL prefix validation](#disable-webhook-url-prefix-validation) - [Enable custom patterns' validation](#enable-custom-patterns-validation) @@ -70,6 +71,7 @@ information. - Configurable timeouts - Configurable retry support - Support for overriding the default `http.Client` +- Support for overriding default project-specific user agent ## Project Status @@ -185,6 +187,12 @@ This is an example of a simple client application which uses this library. File: [basic](./examples/basic/main.go) +#### Set custom user agent + +This example illustrates setting a custom user agent. + +File: [custom-user-agent](./examples/custom-user-agent/main.go) + #### Add an Action This example illustrates adding an [`OpenUri Action`][msgcard-ref-actions] to diff --git a/doc.go b/doc.go index 81ce0f1..5492584 100644 --- a/doc.go +++ b/doc.go @@ -35,6 +35,8 @@ FEATURES • Support for overriding the default http.Client +• Support for overriding the default project-specific user agent + USAGE diff --git a/examples/custom-user-agent/main.go b/examples/custom-user-agent/main.go new file mode 100644 index 0000000..aa936f3 --- /dev/null +++ b/examples/custom-user-agent/main.go @@ -0,0 +1,52 @@ +// Copyright 2021 Adam Chalkley +// +// https://github.com/atc0005/go-teams-notify +// +// Licensed under the MIT License. See LICENSE file in the project root for +// full license information. + +/* + +This is an example of a simple client application which uses this library. + +Of note: + +- default timeout +- custom user agent +- package-level logging is disabled by default +- validation of known webhook URL prefixes is *enabled* +- simple message submitted to Microsoft Teams consisting of formatted body and + title + +*/ + +package main + +import ( + goteamsnotify "github.com/atc0005/go-teams-notify/v2" +) + +func main() { + _ = sendTheMessage() +} + +func sendTheMessage() error { + // init the client + mstClient := goteamsnotify.NewClient() + + // override the project-specific default user agent + mstClient.SetUserAgent("go-teams-notify-example/1.0") + + // setup webhook url + webhookUrl := "https://outlook.office.com/webhook/YOUR_WEBHOOK_URL_OF_TEAMS_CHANNEL" + + // setup message card + msgCard := goteamsnotify.NewMessageCard() + msgCard.Title = "Hello world" + msgCard.Text = "Here are some examples of formatted stuff like " + + "
* this list itself
* **bold**
* *italic*
* ***bolditalic***" + msgCard.ThemeColor = "#DF813D" + + // send + return mstClient.Send(webhookUrl, msgCard) +} diff --git a/send.go b/send.go index a53567e..dfb954e 100644 --- a/send.go +++ b/send.go @@ -69,6 +69,14 @@ const ExpectedWebhookURLResponseText string = "1" // before it times out and is cancelled. const DefaultWebhookSendTimeout = 5 * time.Second +// DefaultUserAgent is the project-specific user agent used when submitting +// messages unless overridden by client code. This replaces the Go default +// user agent value of "Go-http-client/1.1". +// +// The major.minor numbers reflect when this project first diverged from the +// "upstream" or parent project. +const DefaultUserAgent string = "go-teams-notify/2.2" + // ErrWebhookURLUnexpected is returned when a provided webhook URL does // not match a set of confirmed webhook URL patterns. var ErrWebhookURLUnexpected = errors.New("webhook URL does not match one of expected patterns") @@ -90,6 +98,7 @@ type API interface { SendWithContext(ctx context.Context, webhookURL string, webhookMessage MessageCard) error SendWithRetry(ctx context.Context, webhookURL string, webhookMessage MessageCard, retries int, retriesDelay int) error SetHTTPClient(httpClient *http.Client) API + SetUserAgent(userAgent string) API SkipWebhookURLValidationOnSend(skip bool) API AddWebhookURLValidationPatterns(patterns ...string) API ValidateWebhook(webhookURL string) error @@ -97,6 +106,7 @@ type API interface { type teamsClient struct { httpClient *http.Client + userAgent string webhookURLValidationPatterns []string skipWebhookURLValidation bool } @@ -142,6 +152,14 @@ func (c *teamsClient) SetHTTPClient(httpClient *http.Client) API { return c } +// SetUserAgent accepts a custom user agent string. This custom user agent is +// used when submitting messages to Microsoft Teams. +func (c *teamsClient) SetUserAgent(userAgent string) API { + c.userAgent = userAgent + + return c +} + func (c *teamsClient) AddWebhookURLValidationPatterns(patterns ...string) API { c.webhookURLValidationPatterns = append(c.webhookURLValidationPatterns, patterns...) return c @@ -190,6 +208,14 @@ func (c teamsClient) SendWithContext(ctx context.Context, webhookURL string, web req, _ := http.NewRequestWithContext(ctx, http.MethodPost, webhookURL, webhookMessageBuffer) req.Header.Add("Content-Type", "application/json;charset=utf-8") + // If provided, override the project-specific user agent with custom value. + switch { + case c.userAgent != "": + req.Header.Set("User-Agent", c.userAgent) + default: + req.Header.Set("User-Agent", DefaultUserAgent) + } + // do the request res, err := c.httpClient.Do(req) if err != nil {