Documentation
¶
Overview ¶
smsbao
Index ¶
- Constants
- Variables
- func EmailCodeKey(email string, codeType CodeType) string
- func EmailCodeStatusKey(email string, codeType CodeType) string
- func EmailRateLimitKey(email string, codeType CodeType) string
- func EmailVerifyFailKey(email string, codeType CodeType) string
- func EmailVerifyLockKey(email string, codeType CodeType) string
- func IsTestCodeEnabled(cfg *config.Config) bool
- func MatchTestCode(cfg *config.Config, code string) bool
- func ValidateEmailAddress(email string) error
- func ValidateSMTPConfiguration(smtpAddr, fromAddr, password string) error
- func ValidateTestCodeConfig(cfg *config.Config) error
- type AliyunInternationalProvider
- type AliyunProvider
- type CodeType
- type EmailService
- func (s *EmailService) ClearManagerCodeIfAttempt(ctx context.Context, email, attemptID string) error
- func (s *EmailService) EmailSendRateLimitRetryAfter(email string, codeType CodeType) (int, error)
- func (s *EmailService) InvalidateManagerCode(ctx context.Context, email string) error
- func (s *EmailService) PreflightSMTP(ctx context.Context) error
- func (s *EmailService) SendHTMLEmail(ctx context.Context, to, subject, htmlBody string) error
- func (s *EmailService) SendTransactionalHTML(ctx context.Context, to, subject, htmlBody, plainBody string) error
- func (s *EmailService) SendVerifyCode(ctx context.Context, email string, codeType CodeType, lang string) error
- func (s *EmailService) SendVerifyCodeTracked(ctx context.Context, email string, codeType CodeType, lang string) error
- func (s *EmailService) SendVerifyCodeTrackedWithAttempt(ctx context.Context, email string, codeType CodeType, ...) error
- func (s *EmailService) Verify(ctx context.Context, email, code string, codeType CodeType) error
- func (s *EmailService) VerifyManagerCodeAtomically(ctx context.Context, email, code, challengeID string, ...) error
- type IEmailService
- type ISMSProvider
- type ISMSService
- type ManagerCodeLockedError
- type SMSService
- type SMTPSettingsProvider
- type SmsbaoProvider
- type UnismsProvider
Constants ¶
const CacheKeyEmailCode = "emailcode:"
const ( // CacheKeySMSCode 短信验证码的缓存key CacheKeySMSCode string = "smscode:" )
Variables ¶
var ErrEmailSendRateLimited = errors.New("email resend cooldown active, retry in 1 minute")
ErrEmailSendRateLimited is returned by SendVerifyCode when the per-address 1-minute resend cooldown is still active. It is a client-actionable condition (HTTP 429), not an internal failure — callers should branch on it with errors.Is rather than collapsing it onto a generic send-failure code.
var (
ErrManagerCodeInvalid = errors.New("invalid manager verification code")
)
var ErrManagerCodeLocked = errors.New("too many failed attempts, locked for 10 minutes")
ErrManagerCodeLocked is a sentinel for errors.Is checks; the concrete error type is *ManagerCodeLockedError which carries the remaining TTL.
Functions ¶
func EmailCodeKey ¶ added in v1.17.0
The key helpers are shared by the manager MFA flow and the ordinary email login flow. CodeType is part of every control key so a public-user code cannot consume or lock a manager-console code for the same mailbox.
func EmailCodeStatusKey ¶ added in v1.17.0
func EmailRateLimitKey ¶ added in v1.17.0
func EmailVerifyFailKey ¶ added in v1.17.0
func EmailVerifyLockKey ¶ added in v1.17.0
func IsTestCodeEnabled ¶
IsTestCodeEnabled 仅在非 release 模式且配置了 SMSCode 时返回 true。 release 模式永远返回 false,避免通过配置热更新把测试验证码打开成万能验证码。
func MatchTestCode ¶
MatchTestCode 在 IsTestCodeEnabled 为 true 时,比较用户输入(去空白)与配置的 SMSCode。
func ValidateEmailAddress ¶ added in v1.17.0
ValidateEmailAddress accepts only a bare RFC-style mailbox. Display-name forms are valid in a message header but are not a safe SMTP envelope sender for this configuration field.
func ValidateSMTPConfiguration ¶ added in v1.17.0
ValidateSMTPConfiguration validates the complete effective configuration before any network operation. In particular, accepting a syntactically non-empty but invalid MAIL FROM would let an SMTP server reject MFA mail after the policy had already been enabled.
func ValidateTestCodeConfig ¶
ValidateTestCodeConfig 在启动时校验:release 模式下不允许配置 SMSCode。
Types ¶
type AliyunProvider ¶
type CodeType ¶
type CodeType int
CodeType 验证码类型
const ( // CodeTypeRegister 注册 CodeTypeRegister CodeType = iota // CodeTypePayPWD 支付密码 CodeTypePayPWD // CodeTypeForgetLoginPWD 忘记登录密码 CodeTypeForgetLoginPWD // CodeTypeCheckMobile 校验指定手机号是否正确 CodeTypeCheckMobile // DestroyAccount 注销账号 CodeTypeDestroyAccount CodeTypeEmailLogin // CodeTypeOIDCBind OIDC 自助绑定 OTP。单独 keyspace 避免与 // register/login/forget-pwd 等流程的 SMS 计数器串扰。 CodeTypeOIDCBind // CodeTypeManagerLogin 管理控制台登录 MFA OTP。必须使用独立的 // 验证码、限流、失败计数和发送状态 key,避免公开用户验证码流程影响 // 管理端登录。 CodeTypeManagerLogin )
type EmailService ¶
EmailService 邮件服务
func NewEmailService ¶
func NewEmailService(ctx *config.Context, settings SMTPSettingsProvider) *EmailService
NewEmailService 创建邮件服务。
settings 为 nil 时退化到读取 cfg.Support.*(yaml 静态值)。生产路径 应传入 common.EnsureSystemSettings(ctx) 以启用 admin 覆盖。参数显式 强制每个 call site 在 nil(yaml-only)和实际注入之间做出选择,避免 静默漏掉 admin 配置入口。
func (*EmailService) ClearManagerCodeIfAttempt ¶ added in v1.17.0
func (s *EmailService) ClearManagerCodeIfAttempt(ctx context.Context, email, attemptID string) error
ClearManagerCodeIfAttempt removes a code only when its status still carries the supplied attempt ID. It is used when an asynchronous SMTP operation loses ownership of its challenge state.
func (*EmailService) EmailSendRateLimitRetryAfter ¶ added in v1.17.0
func (s *EmailService) EmailSendRateLimitRetryAfter(email string, codeType CodeType) (int, error)
EmailSendRateLimitRetryAfter returns the remaining mailbox cooldown in seconds. It is used by manager-console MFA to turn the shared email cooldown into a client-actionable retry response without exposing Redis errors or changing ordinary-user behavior.
func (*EmailService) InvalidateManagerCode ¶ added in v1.17.0
func (s *EmailService) InvalidateManagerCode(ctx context.Context, email string) error
InvalidateManagerCode atomically removes the shared manager-code/status pair. Challenge creation and send claiming use this to make an older code unusable before any new SMTP operation begins.
func (*EmailService) PreflightSMTP ¶ added in v1.17.0
func (s *EmailService) PreflightSMTP(ctx context.Context) error
PreflightSMTP exercises the same SMTP transaction used for real mail. The sender address is used as the recipient because no new deployment setting is introduced for a probe mailbox. This deliberately sends a real probe; callers invoke it only when enabling/validating manager MFA or during the startup warning check.
func (*EmailService) SendHTMLEmail ¶
func (s *EmailService) SendHTMLEmail(ctx context.Context, to, subject, htmlBody string) error
SendHTMLEmail 直接发送一封 HTML 邮件。subject/body 由调用方负责,本方法 不写 Redis、不限速;速率控制由调用方根据业务场景自行处理。
ctx 的 deadline 会传递到 SMTP 层(dial / 投递阶段);调用方设的 ctx 比 SMTP 默认超时(dial 15s + IO 60s)更紧时,会真正生效。
内容仅含 text/html 单一部分,header 也只补 From/To/Subject/MIME-Version/ Content-Type。短 HTML 事务邮件容易被收件方反垃圾静默丢弃 —— 自检/状态类 邮件请改用 SendTransactionalHTML,带 plaintext 兜底和完整事务邮件 header。
func (*EmailService) SendTransactionalHTML ¶ added in v1.3.0
func (s *EmailService) SendTransactionalHTML(ctx context.Context, to, subject, htmlBody, plainBody string) error
SendTransactionalHTML 发送带 plaintext 兜底 + 标准事务邮件 header 的邮件。
与 SendHTMLEmail 的区别:
- 包成 multipart/alternative,plaintext + HTML 双版本
- 补 Date / Message-ID / Auto-Submitted / List-Unsubscribe 等反垃圾过滤 期望看到的事务邮件特征(故意不发 Precedence: bulk,详见 buildTransactional Message 中的注释 —— 部分 MTA 会把它解释成"不要生成退信",跟本路径用于 诊断的目的相反)
经验验证:阿里云 SMTP → mininglamp.com 这条链路,只发极简 HTML 单一部分 (~300 字节)的测试邮件会被收件方静默丢弃,既不入收件箱也不入垃圾夹也 不退信;同样的链路、同样的凭据,改成 multipart/alternative + 标准 header (~2KB) 后能正常入箱。该方法把这套包装内化,所有"系统自检 / 邀请 / 通知" 类事务邮件应该走这条路径。
plainBody 必须由调用方提供(避免依赖脆弱的"从 HTML strip 标签"启发式)。 htmlBody 为空时,plaintext 仍会被发出(降级体验,但通路工作)。
func (*EmailService) SendVerifyCode ¶
func (s *EmailService) SendVerifyCode(ctx context.Context, email string, codeType CodeType, lang string) error
SendVerifyCode 发送验证码。
主题/正文由 emailtmpl 按 lang 渲染(外置 per-lang 模板,issue #221);走 SendTransactionalHTML 而非极简 sendEmail —— 验证码是高价值事务邮件,带 plaintext 兜底 + 标准事务邮件 header 可显著降低被反垃圾静默丢弃的概率。
func (*EmailService) SendVerifyCodeTracked ¶ added in v1.17.0
func (s *EmailService) SendVerifyCodeTracked(ctx context.Context, email string, codeType CodeType, lang string) error
SendVerifyCodeTracked is the delivery-confirmed variant used by manager MFA. It writes a pending status before SMTP, changes it to sent only after the SMTP transaction returns nil, and removes the code on every failure path. Ordinary user flows continue through SendVerifyCode and retain the legacy missing-status compatibility behavior.
func (*EmailService) SendVerifyCodeTrackedWithAttempt ¶ added in v1.17.0
func (s *EmailService) SendVerifyCodeTrackedWithAttempt(ctx context.Context, email string, codeType CodeType, lang, attemptID, sendStateKey string) error
SendVerifyCodeTrackedWithAttempt is the manager-console variant whose Redis status is bound to a caller-owned attempt ID and send-state key. A slow SMTP request that returns after its 120s send lock has been replaced cannot mark a newer attempt as sent, nor can its cleanup delete the newer code.
func (*EmailService) VerifyManagerCodeAtomically ¶ added in v1.17.0
func (s *EmailService) VerifyManagerCodeAtomically(ctx context.Context, email, code, challengeID string, activeKey, sendStateKey, challengeKey string) error
VerifyManagerCodeAtomically verifies and consumes a manager OTP in one Redis script. The script also binds the email status to the active challenge's sent attempt, so a code from an older challenge cannot be reused by a newer challenge for the same mailbox. A successful consume also removes the challenge and UID active index before the caller proceeds to token issuance; this makes the password-validated challenge single-use even if token issuance later fails.
type IEmailService ¶
type IEmailService interface {
// 发送验证码。lang 为收件人内容语言(BCP-47),用于渲染主题与正文;
// 调用方通常传 i18n.OutboundLanguage(ctx),其会兜底到 OCTO_DEFAULT_LANGUAGE。
SendVerifyCode(ctx context.Context, email string, codeType CodeType, lang string) error
// 验证验证码(销毁缓存)
Verify(ctx context.Context, email, code string, codeType CodeType) error
// SendHTMLEmail 发送一封 HTML 邮件(不走频率限制 / 验证码缓存,由调用方自己控制)
SendHTMLEmail(ctx context.Context, to, subject, htmlBody string) error
// SendTransactionalHTML 发送一封带 plaintext 兜底 + 标准事务邮件 header 的邮件。
// 收件方反垃圾过滤对极简 HTML-only 事务邮件常常静默丢弃;这条路径包成
// multipart/alternative,补上 Date / Message-ID / Auto-Submitted /
// List-Unsubscribe 等 header,显著降低被丢的概率。
SendTransactionalHTML(ctx context.Context, to, subject, htmlBody, plainBody string) error
}
IEmailService 邮件服务接口
type ISMSProvider ¶
func NewAliyunInternationalProvider ¶
func NewAliyunInternationalProvider(ctx *config.Context) ISMSProvider
NewAliyunInternationalProvider 创建短信服务
func NewAliyunProvider ¶
func NewAliyunProvider(ctx *config.Context) ISMSProvider
NewAliyunProvider 创建短信服务
func NewSmsbaoProvider ¶
func NewSmsbaoProvider(ctx *config.Context) ISMSProvider
NewSmsbaoProvider 创建短信服务
func NewUnismsProvider ¶
func NewUnismsProvider(ctx *config.Context) ISMSProvider
NewUnismsProvider 创建短信服务
type ISMSService ¶
type ISMSService interface {
// 发送验证码
SendVerifyCode(ctx context.Context, zone, phone string, codeType CodeType) error
// 验证验证码(销毁缓存)
Verify(ctx context.Context, zone, phone, code string, codeType CodeType) error
}
ISMSService ISMSService
type ManagerCodeLockedError ¶ added in v1.17.0
type ManagerCodeLockedError struct {
RetryAfter int
}
ManagerCodeLockedError is returned when verify attempts are exhausted and the operator is locked out for ten minutes. RetryAfter is the remaining lock TTL in seconds (>= 1) so callers can surface a countdown.
func (*ManagerCodeLockedError) Error ¶ added in v1.17.0
func (e *ManagerCodeLockedError) Error() string
func (*ManagerCodeLockedError) Is ¶ added in v1.17.0
func (e *ManagerCodeLockedError) Is(target error) bool
type SMSService ¶
SMSService 短信服务
func (*SMSService) SendVerifyCode ¶
func (s *SMSService) SendVerifyCode(ctx context.Context, zone, phone string, codeType CodeType) error
SendVerifyCode 发送验证码
type SMTPSettingsProvider ¶ added in v1.3.0
type SMTPSettingsProvider interface {
SupportEmail() string
SupportEmailSmtp() string
SupportEmailPwd() string
}
SMTPSettingsProvider exposes the admin-tunable SMTP config to EmailService without creating an import dependency on modules/common (which itself imports modules/base/common — a cycle if we depended back). Any type that implements these three getters can drive the email sender; the production implementation lives in modules/common.SystemSettings.
type SmsbaoProvider ¶
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package emailtmpl renders outbound transactional email (subject + HTML + plaintext) from per-language templates embedded at build time.
|
Package emailtmpl renders outbound transactional email (subject + HTML + plaintext) from per-language templates embedded at build time. |
|
Package msgtmpl renders outbound IM / push message bodies from per-language template sets embedded at build time.
|
Package msgtmpl renders outbound IM / push message bodies from per-language template sets embedded at build time. |