Help us shape the future of Go! Take the 2026 Go Developer Survey

ocinotifications

package
v1.9.1 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2026 License: MIT Imports: 30 Imported by: 0

README

OCI Notifications

Parity grade: B · SDK github.com/oracle/oci-go-sdk/v65@v65.126.2 · last audited 2026-10-27 (3a4fe760a)

Coverage

Metric Value
PARITY entries audited 16 (11 ok, 5 partial)
Feature families 10 (9 ok, 1 partial)
Known gaps 7
Deferred items 0
Resource leaks unknown
Known gaps
  • EMAIL, SMS, SLACK and PAGERDUTY messages are recorded but never sent; Slack formatting, PagerDuty incident creation and friendly email formatting are not modelled.
  • Whether CUSTOM_HTTPS, SLACK, SMS and PAGERDUTY subscriptions start PENDING or ACTIVE is recalled from the documentation, not verified; the confirmation body and the X-OCI-NS-MessageType values are unverified.
  • Signed deliveries (X-OCI-NS-Signature, X-OCI-NS-Timestamp, X-OCI-NS-SignatureVersion, X-OCI-NS-SigningCertURL) and the friendly-formatting setting are not implemented.
  • The publish rate (60 messages per minute per topic) and per-subscription delivery rates are not enforced; SMS is not restricted to Announcements, Monitoring and Connector Hub messages.
  • The maxRetryDuration range (10 s to 24 h), topic name rules, the status codes for DeleteSubscription (204) and DeleteTopic (202), and the error codes for bad confirmation tokens are unverified.
  • Deleted topics and unsubscribed subscriptions disappear instead of passing through a DELETED state.
  • Topic and subscription tagging is stored verbatim; opc-retry-token idempotency, IAM policy checks, resource principals and instance principals are not applied; only API-key signatures are verified.

More

Documentation

Index

Constants

View Source 
const DefaultPort = 8157

DefaultPort is the dedicated listener's default TCP port.

View Source 
const (
	// Region is the fixed region baked into emulated OCIDs.
	Region = "us-ashburn-1"
)

Variables

View Source 
var ErrEndpointStatus = errors.New("endpoint answered")

ErrEndpointStatus marks a delivery attempt that the endpoint answered with a non-2xx status.

View Source 
var ErrNilAppContext = errors.New("ocinotifications: nil app context")

ErrNilAppContext is returned when Init is called with a nil AppContext.

View Source 
var ErrSnapshotNull = errors.New("ocinotifications: null entry in snapshot")

ErrSnapshotNull is returned when a snapshot contains a null entry.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	Code    string
	Message string
	Status  int
}

APIError is an OCI error response: HTTP status plus the `code` and `message` body fields.

func (*APIError) Error 

func (e *APIError) Error() string

type ConfigProvider 

type ConfigProvider interface {
	GetOCINotificationsSettings() Settings
}

ConfigProvider extracts OCI Notifications configuration from the AppContext Config.

type ConfirmationWire 

type ConfirmationWire struct {
	TopicName      string `json:"topicName"`
	TopicID        string `json:"topicId"`
	Endpoint       string `json:"endpoint"`
	UnsubscribeURL string `json:"unsubscribeUrl"`
	Message        string `json:"message"`
	SubscriptionID string `json:"subscriptionId"`
}

type CreateSubscriptionIn 

type CreateSubscriptionIn struct {
	Tags
	Metadata    *string `json:"metadata"`
	TopicID     string  `json:"topicId"`
	Compartment string  `json:"compartmentId"`
	Protocol    string  `json:"protocol"`
	Endpoint    string  `json:"endpoint"`
}

CreateSubscriptionIn is the CreateSubscription request body.

type CreateTopicIn 

type CreateTopicIn struct {
	Tags
	Description *string `json:"description"`
	Name        string  `json:"name"`
	Compartment string  `json:"compartmentId"`
}

CreateTopicIn is the CreateTopic request body.

type Delivery 

type Delivery struct {
	Published       time.Time `json:"published"`
	NextAttempt     time.Time `json:"nextAttempt"`
	Deadline        time.Time `json:"deadline"`
	Completed       time.Time `json:"completed"`
	SubscriptionID  string    `json:"subscriptionId"`
	Title           string    `json:"title,omitempty"`
	Kind            string    `json:"kind"`
	MessageID       string    `json:"messageId"`
	TopicID         string    `json:"topicId"`
	TopicName       string    `json:"topicName"`
	LastError       string    `json:"lastError,omitempty"`
	Protocol        string    `json:"protocol"`
	Endpoint        string    `json:"endpoint"`
	ID              string    `json:"id"`
	Body            string    `json:"body"`
	MessageType     string    `json:"messageType"`
	ConfirmationURL string    `json:"confirmationUrl,omitempty"`
	UnsubscribeURL  string    `json:"unsubscribeUrl,omitempty"`
	Status          string    `json:"status"`
	Attempts        int       `json:"attempts"`
	LastStatus      int       `json:"lastStatus,omitempty"`
	Seq             int64     `json:"seq"`
	// contains filtered or unexported fields
}

Delivery records one message or confirmation handed to a subscription endpoint.

type DeliveryView 

type DeliveryView = Delivery

DeliveryView is a delivery record as reported by the admin endpoint.

type FunctionInvoker 

type FunctionInvoker func(ctx context.Context, functionID string, header http.Header, body []byte) error

FunctionInvoker invokes an OCI Function by OCID with the message as payload.

type Handler 

type Handler struct {
	Backend *InMemoryBackend

	Port        int
	EnforceAuth bool
	// contains filtered or unexported fields
}

Handler serves OCI Notifications: topics, subscriptions and message publishing.

func NewHandler 

func NewHandler(backend *InMemoryBackend) *Handler

NewHandler creates a Handler; callers override Port and EnforceAuth from Settings.

func (*Handler) ExtractOperation 

func (h *Handler) ExtractOperation(c *echo.Context) string

ExtractOperation returns the operation name for metrics.

func (*Handler) ExtractResource 

func (h *Handler) ExtractResource(c *echo.Context) string

ExtractResource returns the addressed resource id for metrics.

func (*Handler) GetSupportedOperations 

func (h *Handler) GetSupportedOperations() []string

GetSupportedOperations lists the supported operations.

func (*Handler) Handler 

func (h *Handler) Handler() echo.HandlerFunc

Handler returns the Echo handler for all OCINotifications requests.

func (*Handler) MatchPriority 

func (h *Handler) MatchPriority() int

MatchPriority is irrelevant because RouteMatcher never matches.

func (*Handler) Name 

func (h *Handler) Name() string

Name returns the service name.

func (*Handler) Reset 

func (h *Handler) Reset()

Reset clears all in-memory state.

func (*Handler) Restore 

func (h *Handler) Restore(ctx context.Context, data []byte) error

Restore implements persistence.Persistable by delegating to the backend.

func (*Handler) RouteMatcher 

func (h *Handler) RouteMatcher() service.Matcher

RouteMatcher never matches: OCINotifications runs on its own listener.

func (*Handler) Shutdown 

func (h *Handler) Shutdown(ctx context.Context)

Shutdown stops the listener and the sweeper.

func (*Handler) Snapshot 

func (h *Handler) Snapshot(ctx context.Context) []byte

Snapshot implements persistence.Persistable by delegating to the backend.

func (*Handler) StartWorker 

func (h *Handler) StartWorker(ctx context.Context) error

StartWorker binds the dedicated listener synchronously so a port conflict is returned to the caller.

func (*Handler) Trusted 

func (h *Handler) Trusted() echo.HandlerFunc

Trusted returns a handler that skips request-signature verification, for the in-process dashboard proxy.

type InMemoryBackend 

type InMemoryBackend struct {
	Auth *ociauth.Registry
	// contains filtered or unexported fields
}

InMemoryBackend holds every topic, subscription and delivery under one lock.

func NewInMemoryBackend 

func NewInMemoryBackend() *InMemoryBackend

NewInMemoryBackend creates an empty backend.

func (*InMemoryBackend) ChangeSubscriptionCompartment 

func (b *InMemoryBackend) ChangeSubscriptionCompartment(id, ifMatch, compartment string) error

ChangeSubscriptionCompartment moves a subscription to another compartment.

func (*InMemoryBackend) ChangeTopicCompartment 

func (b *InMemoryBackend) ChangeTopicCompartment(id, ifMatch, compartment string) error

ChangeTopicCompartment moves a topic to another compartment.

func (*InMemoryBackend) Compartments 

func (b *InMemoryBackend) Compartments() []string

Compartments lists the distinct compartments that hold live topics or subscriptions.

func (*InMemoryBackend) ConfirmSubscription 

func (b *InMemoryBackend) ConfirmSubscription(id, token, protocol string) (ConfirmationWire, error)

ConfirmSubscription activates a PENDING subscription from the token sent to its endpoint.

func (*InMemoryBackend) CreateSubscription 

func (b *InMemoryBackend) CreateSubscription(in CreateSubscriptionIn, baseURL string) (SubWire, error)

CreateSubscription subscribes an endpoint to a topic; protocols that need it start PENDING and are sent a confirmation.

func (*InMemoryBackend) CreateTopic 

func (b *InMemoryBackend) CreateTopic(in CreateTopicIn, endpoint string) (TopicWire, error)

CreateTopic creates a topic in CREATING state.

func (*InMemoryBackend) DeleteSubscription 

func (b *InMemoryBackend) DeleteSubscription(id, ifMatch string) error

DeleteSubscription removes a subscription and its deliveries.

func (*InMemoryBackend) DeleteTopic 

func (b *InMemoryBackend) DeleteTopic(id, ifMatch string) error

DeleteTopic moves a topic to DELETING; its subscriptions go with it once the transition completes.

func (*InMemoryBackend) DeliverDue 

func (b *InMemoryBackend) DeliverDue(ctx context.Context, spawn func(func()))

DeliverDue starts an attempt for every pending delivery whose time has come, using spawn to run each one.

func (*InMemoryBackend) Deliveries 

func (b *InMemoryBackend) Deliveries(topicID, subscriptionID string) []DeliveryView

Deliveries lists delivery records, optionally filtered by topic and subscription, oldest first.

func (*InMemoryBackend) GetSubscription 

func (b *InMemoryBackend) GetSubscription(id string) (SubWire, error)

GetSubscription returns one subscription.

func (*InMemoryBackend) GetTopic 

func (b *InMemoryBackend) GetTopic(id, endpoint string) (TopicWire, error)

GetTopic returns one topic.

func (*InMemoryBackend) Kick 

func (b *InMemoryBackend) Kick()

Kick wakes the dispatcher so it re-evaluates which deliveries are due.

func (*InMemoryBackend) ListSubscriptions 

func (b *InMemoryBackend) ListSubscriptions(
	compartment, topicID string,
	o ListOpts,
) (page.Page[subSummaryWire], error)

ListSubscriptions lists the subscriptions of a compartment, optionally of one topic.

func (*InMemoryBackend) ListTopics 

func (b *InMemoryBackend) ListTopics(
	compartment, id, name, state, endpoint string,
	o ListOpts,
) (page.Page[TopicWire], error)

ListTopics lists the topics of a compartment.

func (*InMemoryBackend) NextDue 

func (b *InMemoryBackend) NextDue() (time.Duration, func(time.Duration) <-chan time.Time)

NextDue reports how long until the earliest pending delivery is due; negative when none is waiting.

func (*InMemoryBackend) PublishMessage 

func (b *InMemoryBackend) PublishMessage(topicID, messageType string, in PublishIn) (PublishWire, error)

PublishMessage fans a message out to every ACTIVE subscription of a topic.

func (*InMemoryBackend) ResendConfirmation 

func (b *InMemoryBackend) ResendConfirmation(id string) (SubWire, string, error)

ResendConfirmation sends a PENDING subscription's confirmation again.

func (*InMemoryBackend) Reset 

func (b *InMemoryBackend) Reset()

Reset clears all state.

func (*InMemoryBackend) Restore 

func (b *InMemoryBackend) Restore(ctx context.Context, data []byte) error

Restore loads backend state from a snapshot.

func (*InMemoryBackend) SetClock 

func (b *InMemoryBackend) SetClock(now func() time.Time)

SetClock injects the time source used for lifecycle transitions and delivery retries.

func (*InMemoryBackend) SetFunctionInvoker 

func (b *InMemoryBackend) SetFunctionInvoker(fn FunctionInvoker)

SetFunctionInvoker wires ORACLE_FUNCTIONS subscriptions to the OCI Functions backend.

func (*InMemoryBackend) SetTimer 

func (b *InMemoryBackend) SetTimer(after func(time.Duration) <-chan time.Time)

SetTimer injects the wait the dispatcher uses until the next retry; it must return a channel firing after d.

func (*InMemoryBackend) SetTransition 

func (b *InMemoryBackend) SetTransition(d time.Duration)

SetTransition sets how long CREATING and DELETING topic states last.

func (*InMemoryBackend) Snapshot 

func (b *InMemoryBackend) Snapshot(ctx context.Context) []byte

Snapshot serialises the backend state, including registered API keys.

func (*InMemoryBackend) Sweep 

func (b *InMemoryBackend) Sweep()

Sweep applies topic lifecycle transitions against the backend clock; deleted topics take their subscriptions along.

func (*InMemoryBackend) TopicActive 

func (b *InMemoryBackend) TopicActive(id string) bool

TopicActive reports whether id is an ACTIVE topic.

func (*InMemoryBackend) Unsubscribe 

func (b *InMemoryBackend) Unsubscribe(id, token, protocol string) (string, error)

Unsubscribe removes a subscription from the token embedded in its unsubscribe link.

func (*InMemoryBackend) UpdateSubscription 

func (b *InMemoryBackend) UpdateSubscription(
	id, ifMatch string,
	in UpdateSubscriptionIn,
) (UpdateSubscriptionIn, string, error)

UpdateSubscription changes a subscription's delivery policy and tags.

func (*InMemoryBackend) UpdateTopic 

func (b *InMemoryBackend) UpdateTopic(id, ifMatch, endpoint string, in UpdateTopicIn) (TopicWire, error)

UpdateTopic changes a topic's description and tags.

type ListOpts 

type ListOpts struct {
	SortBy string
	Order  string
	Page   string
	Limit  int
}

ListOpts carries the shared list query parameters.

type Provider 

type Provider struct{}

Provider implements service.Provider for OCI Notifications. It runs on its own listener (see Handler.StartWorker) and never matches on the shared AWS router.

func (*Provider) Init 

func (p *Provider) Init(ctx *service.AppContext) (service.Registerable, error)

Init creates the backend and handler; the port is bound in StartWorker.

func (*Provider) Name 

func (p *Provider) Name() string

Name returns the service provider name.

type PublishIn 

type PublishIn struct {
	Title *string `json:"title"`
	Body  *string `json:"body"`
}

PublishIn is the PublishMessage request body.

type PublishWire 

type PublishWire struct {
	TimeStamp time.Time `json:"timeStamp"`
	MessageID string    `json:"messageId"`
}

type Settings 

type Settings struct {
	Port int `` //nolint:lll // config struct tags are intentionally verbose
	/* 230-byte string literal not displayed */
	EnforceAuth bool `` //nolint:lll // config struct tags are intentionally verbose
	/* 229-byte string literal not displayed */
}

Settings holds service-level configuration, embedded in the root CLI as CLI.OCINotifications.

func DefaultSettings 

func DefaultSettings() Settings

DefaultSettings returns the settings used when no ConfigProvider is available.

type SubWire 

type SubWire struct {
	FreeformTags   map[string]string         `json:"freeformTags,omitempty"`
	DefinedTags    map[string]map[string]any `json:"definedTags,omitempty"`
	ID             string                    `json:"id"`
	TopicID        string                    `json:"topicId"`
	Protocol       string                    `json:"protocol"`
	Endpoint       string                    `json:"endpoint"`
	LifecycleState string                    `json:"lifecycleState"`
	CompartmentID  string                    `json:"compartmentId"`
	DeliverPolicy  string                    `json:"deliverPolicy"`
	Etag           string                    `json:"etag"`
	CreatedTime    int64                     `json:"createdTime"`
}

type Subscription 

type Subscription struct {
	TimeCreated   time.Time `json:"timeCreated"`
	Tags          Tags      `json:"tags"`
	ID            string    `json:"id"`
	TopicID       string    `json:"topicId"`
	CompartmentID string    `json:"compartmentId"`
	Protocol      string    `json:"protocol"`
	Endpoint      string    `json:"endpoint"`
	State         string    `json:"state"`
	Metadata      string    `json:"metadata,omitempty"`
	BaseURL       string    `json:"baseUrl"`
	ConfirmToken  string    `json:"confirmToken"`
	UnsubToken    string    `json:"unsubToken"`
	Etag          string    `json:"etag"`
	MaxRetryMs    int       `json:"maxRetryMs"`
	Seq           int64     `json:"seq"`
}

Subscription is one endpoint subscribed to a topic.

type Tags 

type Tags struct {
	FreeformTags map[string]string         `json:"freeformTags,omitempty"`
	DefinedTags  map[string]map[string]any `json:"definedTags,omitempty"`
}

Tags are the shared freeform and defined tag sets of a resource.

type Topic 

type Topic struct {
	TimeCreated   time.Time  `json:"timeCreated"`
	TransitionAt  *time.Time `json:"transitionAt,omitempty"`
	Tags          Tags       `json:"tags"`
	ID            string     `json:"id"`
	ShortID       string     `json:"shortId"`
	CompartmentID string     `json:"compartmentId"`
	Name          string     `json:"name"`
	Description   string     `json:"description"`
	State         string     `json:"state"`
	Etag          string     `json:"etag"`
	Seq           int64      `json:"seq"`
}

Topic is a notification topic.

type TopicWire 

type TopicWire struct {
	TimeCreated    time.Time                 `json:"timeCreated"`
	FreeformTags   map[string]string         `json:"freeformTags,omitempty"`
	DefinedTags    map[string]map[string]any `json:"definedTags,omitempty"`
	Name           string                    `json:"name"`
	TopicID        string                    `json:"topicId"`
	CompartmentID  string                    `json:"compartmentId"`
	LifecycleState string                    `json:"lifecycleState"`
	APIEndpoint    string                    `json:"apiEndpoint"`
	ShortTopicID   string                    `json:"shortTopicId"`
	Description    string                    `json:"description,omitempty"`
	Etag           string                    `json:"etag"`
}

type UpdateSubscriptionIn 

type UpdateSubscriptionIn struct {
	Tags
	DeliveryPolicy *deliveryPolicyWire `json:"deliveryPolicy"`
}

UpdateSubscriptionIn is the UpdateSubscription request body.

type UpdateTopicIn 

type UpdateTopicIn struct {
	Tags
	Description *string `json:"description"`
}

UpdateTopicIn is the UpdateTopic request body.

Source Files

View all Source files

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.