### Prosody Integration Package API Example Source: https://github.com/mellium/xmpp/blob/main/design/42_integration_testing.md Shows an example API for a hypothetical `integration/prosody` package, including `ConfigFile` option, `New` command creation, and `Test` function for running Prosody instances as subtests. ```go // ConfigFile is an option that can be used to write a temporary Prosody config file. func ConfigFile(cfg Config) integration.Option ``` ```go // New creates a new, unstarted, Prosody daemon. func New(ctx context.Context, opts ...integration.Option) (*integration.Cmd, error) ``` ```go // Test starts a Prosody instance and returns a function that runs f as a // subtest using t.Run. func Test(ctx context.Context, t *testing.T, opts ...integration.Option) integration.SubtestRunner ``` -------------------------------- ### Minimal Working Example Placeholder Source: https://github.com/mellium/xmpp/blob/main/docs/ISSUE_TEMPLATE/bug_report.md Include a minimal working example of the bug in the issue body. A link to a runnable example on play.golang.org is highly recommended. ```markdown A minimal working example in the body of the issue and a link to play.golang.org where it can be run. ``` -------------------------------- ### Example Commit Message Subject Source: https://github.com/mellium/xmpp/blob/main/docs/CONTRIBUTING.md Commit messages should start with the package name or 'all', followed by a short description of the change. Do not use punctuation at the end of the subject line. ```git commit dial: fix flaky tests ``` -------------------------------- ### Example Usage of integration.Test Source: https://github.com/mellium/xmpp/blob/main/design/42_integration_testing.md Demonstrates the syntax for calling the `integration.Test` function with background context, testing object, and configuration options, followed by a subtest function. ```go integration.Test( context.Background(), t, integration.Cert("localhost"), … )(func(ctx context.Context, t *testing.T, cmd *integration.Cmd) { … }) ``` -------------------------------- ### GetIQ Option Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Creates an IQOption to handle IQ stanzas of type 'get' with a specific XML name. ```go func GetIQ(n xml.Name, h IQHandler) IQOption GetIQ is a shortcut for HandleIQ with the type set to "get". ``` -------------------------------- ### IQMux HandleXMPP Method Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Dispatches an IQ stanza to the most closely matching handler based on the start element's name. ```go func (m *IQMux) HandleXMPP(t xmlstream.TokenReadEncoder, start *xml.StartElement) error HandleXMPP dispatches the IQ to the handler whose pattern most closely matches start.Name. ``` -------------------------------- ### Registering Multiple Handlers with a Single Option Source: https://github.com/mellium/xmpp/blob/main/docs/extensions.md This option registers an example handler that implements both IQHandler and MessageHandler. It groups multiple options into one for the mux.ServeMux. ```go // Handle is an option that registers an example handler that implements // both IQHandler and MessageHandler. func Handle(h Handler) mux.Option { return func(m *ServeMux) { mux.IQ(stanza.GetIQ, xml.Name{Local: "example", Space: NS}, h)(m) mux.Message(stanza.NormalMessage, xml.Name{Local: "example", Space: NS}, h)(m) } } ``` -------------------------------- ### Cmd Option Type and Functions Source: https://github.com/mellium/xmpp/blob/main/design/42_integration_testing.md Defines the `Option` type for configuring commands and provides functions like `Args`, `Cert`, `Log`, `LogXML`, and `TempFile` to customize command behavior and setup. ```go type Option func(cmd *Cmd) error ``` ```go func Args(f ...string) Option ``` ```go func Cert(name string) Option ``` ```go func Log() Option ``` ```go func LogXML() Option ``` ```go func TempFile(cfgFileName string, f func(*Cmd, io.Writer) error) Option ``` -------------------------------- ### Cmd Function Definitions Source: https://github.com/mellium/xmpp/blob/main/design/42_integration_testing.md Provides core functions for managing external commands: `New` to create a command, `Close` to terminate it, `ConfigDir` to get its configuration directory, and `Dial` to connect to a server. ```go func New(ctx context.Context, name string, opts ...Option) (*Cmd, error) ``` ```go func (cmd *Cmd) Close() error ``` ```go func (cmd *Cmd) ConfigDir() string ``` ```go func (cmd *Cmd) Dial(ctx context.Context, j jid.JID, t *testing.T, features ...xmpp.StreamFeature) (*xmpp.Session, error) ``` -------------------------------- ### Example Full Commit Message Source: https://github.com/mellium/xmpp/blob/main/docs/CONTRIBUTING.md The commit message body should explain the change and its necessity in detail, wrapped to 72 characters. Include benchmarks or other data if helpful. Do not use Markdown or HTML. ```git commit dial: fix flaky tests Previously DNS requests were made for A or AAAA records depending on what networks were available. Tests expected AAAA requests so they would fail on machines that only had IPv4 networking. ``` -------------------------------- ### Get Subscription Handler Source: https://github.com/mellium/xmpp/blob/main/design/292_pubsub_notify.md Returns the handler for a given item list namespace. If no exact match is found, a default no-op handler is returned. ```go func (*Subscriptions) Handler(ns string) (h Handler, ok bool) ``` -------------------------------- ### ResultIQ Option Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Creates an IQOption to handle IQ stanzas of type 'result' with a specific XML name. Handlers should check for a nil start element as result IQs may not have a payload. ```go func ResultIQ(n xml.Name, h IQHandler) IQOption ResultIQ is a shortcut for HandleIQ with the type set to "result". Unlike IQs of type get, set, and error, result type IQs may or may not contain a payload. Because of this it is important to check whether the start element is nil in handlers meant to handle result type IQs. ``` -------------------------------- ### SubtestRunner Type and Test Function Source: https://github.com/mellium/xmpp/blob/main/design/42_integration_testing.md Defines the `SubtestRunner` signature and the `Test` function, which starts a command and returns a runner for executing subtests within the integration test. ```go type SubtestRunner func(func(context.Context, *testing.T, *Cmd)) bool ``` ```go func Test(ctx context.Context, name string, t *testing.T, opts ...Option) SubtestRunner ``` -------------------------------- ### Alternative integration.Test Syntax Source: https://github.com/mellium/xmpp/blob/main/design/42_integration_testing.md Illustrates an alternative, more verbose syntax for `integration.Test` where the subtest function and options are passed as arguments directly, followed by an empty invocation. ```go integration.Test( context.Background(), t, func(ctx context.Context, t *testing.T, cmd *integration.Cmd) { … }, integration.Cert("localhost"), … )() ``` -------------------------------- ### Go Environment Details Source: https://github.com/mellium/xmpp/blob/main/docs/ISSUE_TEMPLATE/bug_report.md Include the output of 'go env' within a details tag for detailed environment information. This aids in diagnosing environment-related problems. ```html
go env

``` GO111MODULE="on" GOARCH="amd64" GOBIN="" … ```

``` -------------------------------- ### IBB Handler Open Method Source: https://github.com/mellium/xmpp/blob/main/design/19_ibb.md Initiates a new IBB stream using IQ stanzas as the carrier on a given XMPP session. ```go func (h *Handler) Open(ctx context.Context, s *xmpp.Session, to jid.JID, blockSize uint16) (*Conn, error) Open attempts to create a new IBB stream on the provided session using IQs as the carrier stanza. ``` -------------------------------- ### Roster Item Iterator Interface Source: https://github.com/mellium/xmpp/blob/main/docs/extensions.md Defines the interface for an iterator over roster items, including methods to retrieve the current item, check for more items, get errors, and close the iterator. ```go type Iter struct{} // Item returns the last roster item parsed by the iterator. (i *Iter) Item() Item // Next reports whether there are more items to decode. (i *Iter) Next() bool // Err returns the last error encountered by the iterator (if any). (i *Iter) Err() error // Close indicates that we are finished with the given iterator and processing // the stream may continue. // Calling it multiple times has no effect. (i *Iter) Close() error ``` -------------------------------- ### SetIQ Option Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Creates an IQOption to handle IQ stanzas of type 'set' with a specific XML name. ```go func SetIQ(n xml.Name, h IQHandler) IQOption SetIQ is a shortcut for HandleIQ with the type set to "set". ``` -------------------------------- ### PubSub Namespaces Source: https://github.com/mellium/xmpp/blob/main/design/292_pubsub_notify.md Exports constants for the standard Pub/Sub protocol namespaces. ```go const ( NSEvent = `http://jabber.org/protocol/pubsub#event` NSErrors = `http://jabber.org/protocol/pubsub#errors` NSOptions = `http://jabber.org/protocol/pubsub#subscription-options` ) ``` -------------------------------- ### NewIQMux Function Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Allocates and returns a new IQMux. Options can be provided to configure its behavior. ```go func NewIQMux(opt ...IQOption) *IQMux NewIQMux allocates and returns a new IQMux. ``` -------------------------------- ### Import XMPP Library in Go Source: https://github.com/mellium/xmpp/blob/main/README.md Import the XMPP library or any of its sub-packages into your Go project to begin using its functionalities. ```go import mellium.im/xmpp ``` -------------------------------- ### Handle Function for Service Discovery Source: https://github.com/mellium/xmpp/blob/main/design/28_disco.md Provides an option to configure a multiplexer to handle service discovery requests. It iterates over the multiplexer's handlers and checks for info.FeatureIter implementation. ```go // Handle returns an option that configures a multiplexer to handle service // discovery requests by iterating over its own handlers and checking if they // implement info.FeatureIter. func Handle() mux.Option ``` -------------------------------- ### External Command Structure and Methods Source: https://github.com/mellium/xmpp/blob/main/design/template.md Defines the Cmd struct for external commands and its associated methods: New for creation, Close for cleanup, ConfigDir for configuration directory, and Dial for establishing a connection. ```go // Cmd is an external command being prepared or run. type Cmd struct { *exec.Cmd … } // New creates a new, unstarted, command. func New(ctx context.Context, name string, opts ...Option) (*Cmd, error) // Close kills the command if it is still running and cleans up any // temporary resources that were created. func (cmd *Cmd) Close() error // ConfigDir returns the temporary directory used to store config files. func (cmd *Cmd) ConfigDir() string // Dial attempts to connect to the server by dialing localhost and then // negotiating a stream with the location set to the domainpart of j and the // origin set to j. func (cmd *Cmd) Dial(ctx context.Context, j jid.JID, t *testing.T, features ...xmpp.StreamFeature) (*xmpp.Session, error) ``` -------------------------------- ### Subscription Management Methods Source: https://github.com/mellium/xmpp/blob/main/design/292_pubsub_notify.md Provides methods for subscribing to a pubsub node, subscribing using a HandlerFunc, and unsubscribing. It handles the creation and removal of subscriptions. ```go // Subscribe creates a new subscription to a namespace. // // The namespace should not include the +notify suffix. // If a subscription already exists for the namespace, Subscribe is a noop. func (*Subscriptions) Subscribe(ctx context.Context, to jid.JID, session *xmpp.Session, ns string, h Handler) (Subscription, error) { … } // SubscribeFunc is like Subscribe except it takes a HandlerFunc. func (*Subscriptions) SubscribeFunc(ctx context.Context, to jid.JID, session *xmpp.Session, ns string, h Handler) (Subscription, error) { … } // Unsubscribe removes a subscription and stops handling events. func (*Subscriptions) Unsubscribe(ctx context.Context, ns string) error { … } ``` -------------------------------- ### IQMux Handler Method Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Retrieves the handler for a given IQ type and XML name. Returns a non-nil default handler if no specific handler is found. ```go func (m *IQMux) Handler(iqType stanza.IQType, name xml.Name) (h IQHandler, ok bool) Handler returns the handler to use for an IQ payload with the given name and type. If no handler exists, a default handler is returned (h is always non-nil). ``` -------------------------------- ### Go Version Placeholder Source: https://github.com/mellium/xmpp/blob/main/docs/ISSUE_TEMPLATE/bug_report.md Provide the Go version being used for the bug report. This helps in identifying version-specific issues. ```markdown go version … ``` -------------------------------- ### Define Multiple XML Namespace Constants Source: https://github.com/mellium/xmpp/blob/main/docs/extensions.md When a package implements multiple XEPs or an XEP defines multiple namespaces, export them as prefixed constants (e.g., NSInfo, NSItems). ```go // Namespaces used by this package const ( NSInfo = `http://jabber.org/protocol/disco#info` NSItems = `http://jabber.org/protocol/disco#items` ) ``` -------------------------------- ### HandleIQ Option Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Returns an option that matches IQ payloads by XML name and IQ type. Provides a general way to register handlers, with specific shortcuts available. ```go func HandleIQ(iqType stanza.IQType, n xml.Name, h IQHandler) IQOption HandleIQ returns an option that matches the IQ payload by XML name and IQ type. For readability, users may want to use the GetIQ, SetIQ, ErrorIQ, and ResultIQ shortcuts instead. For more details, see the documentation on IQMux. ``` -------------------------------- ### ServeMux ForFeatures Method Implementation Source: https://github.com/mellium/xmpp/blob/main/design/28_disco.md Implements the info.FeatureIter interface for the ServeMux type. It iterates over all child features of the multiplexer. ```go // ForFeatures implements info.FeatureIter for the mux by iterating over all // child features. func (m *ServeMux) ForFeatures(node string, f func(info.Feature) error) error ``` -------------------------------- ### HandleIQFunc Option Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Returns an option that matches IQ payloads by XML name and IQ type, using an IQHandlerFunc. This allows direct use of functions as handlers. ```go func HandleIQFunc(iqType stanza.IQType, n xml.Name, h IQHandlerFunc) IQOption HandleIQFunc returns an option that matches the IQ payload by XML name and IQ type. ``` -------------------------------- ### Hash Calculation Functions Source: https://github.com/mellium/xmpp/blob/main/design/171_caps.md Provides functions for calculating the entity capabilities verification string. Supports both string and byte slice output forms for efficiency. ```go // Hash generates the entity capabilities verification string. // Its output is suitable for use as a cache key. func Hash(hash.Hash, info.FeatureIter, info.IdentityIter, form.Iter) (string, error) { … } ``` ```go // AppendHash is like Hash except that it appends the output to the provided // byte slice. func AppendHash([]byte, hash.Hash, info.FeatureIter, info.IdentityIter, form.Iter) ([]byte, error) { … } ``` -------------------------------- ### Registering the Subscriptions Handler Source: https://github.com/mellium/xmpp/blob/main/design/292_pubsub_notify.md The `Handle` function provides an option to register the `Subscriptions` handler with a multiplexer, enabling it to process incoming pubsub messages. ```go // Handle returns an option that registers the handler for use with a // multiplexer. func Handle(s *Subscriptions) mux.Option { … } ``` -------------------------------- ### IQHandlerFunc Type Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md An adapter to allow ordinary functions to be used as IQ handlers. It wraps a function with the appropriate signature. ```go type IQHandlerFunc func(iq stanza.IQ, t xmlstream.TokenReadEncoder, start *xml.StartElement) error ``` -------------------------------- ### Info Struct Hash Methods Source: https://github.com/mellium/xmpp/blob/main/design/171_caps.md Methods on the Info struct for generating the entity capabilities verification string. Suitable for use as a cache key. ```go // Hash generates the entity capabilities verification string. // Its output is suitable for use as a cache key. func (Info) Hash(h hash.Hash) string {… } ``` ```go // AppendHash is like Hash except that it appends the output string to the // provided byte slice. func (Info) AppendHash(dst []byte, h hash.Hash) []byte { … } ``` -------------------------------- ### Event Handler Source: https://github.com/mellium/xmpp/blob/main/design/292_pubsub_notify.md Interface and adapter for handling pubsub events. ```APIDOC ## Interface Handler ### Description Responds to pubsub events. Implemented by types in external packages to allow them to be registered against a pubsub service and respond to events. ### Methods #### HandleEvent ```go func (h Handler) HandleEvent(stanza.Message, pubsub.Iter) error ``` Handles a pubsub event. ## type HandlerFunc ### Description An adapter to allow the use of ordinary functions as event handlers. ### Methods #### HandleEvent ```go func (f HandlerFunc) HandleEvent(msg stanza.Message, iter pubsub.Iter) error ``` Calls the underlying function `f(msg, iter)`. ``` -------------------------------- ### Roster Package Iterator Next Method Implementation Source: https://github.com/mellium/xmpp/blob/main/docs/extensions.md Provides the implementation for the `Next` method of a roster iterator, showing how to decode child elements from the stream and handle potential errors. ```go // Next returns true if there are more items to decode. func (i *Iter) Next() bool { if i.err != nil || !i.iter.Next() { return false } start, r := i.iter.Current() d := xml.NewTokenDecoder(r) item := Item{} i.err = d.DecodeElement(&item, start) if i.err != nil { return false } i.current = item return true } ``` -------------------------------- ### IQHandler Interface Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Defines the interface for handling IQ stanzas. Implementations respond to IQ stanzas. ```go type IQHandler interface { HandleIQ(iq stanza.IQ, t xmlstream.TokenReadEncoder, start *xml.StartElement) error } ``` -------------------------------- ### Exporting Message Styling Tests Source: https://github.com/mellium/xmpp/blob/main/styling/README.md Run this command in the styling directory to export test cases to decoder_tests.json. ```bash go test -tags export ``` -------------------------------- ### Subscription Details Structure Source: https://github.com/mellium/xmpp/blob/main/design/292_pubsub_notify.md The `Subscription` struct holds details about a specific subscription to a pubsub node, including its ID, node, address, state, and configuration requirements. ```go // Subscription is a description of a particular subscription for which we will // receive events. type Subscription struct { ID string Node string Addr jid.JID Subscription SubType Configurable bool ConfigRequired bool } // TokenReader satisfies the xmlstream.Marshaler interface. func (Subscription) TokenReader() xml.TokenReader { … } // WriteXML satisfies the xmlstream.WriterTo interface. // It is like MarshalXML except it writes tokens to w. func (Subscription) WriteXML(w xmlstream.TokenWriter) (n int, err error) { … } // MarshalXML implements xml.Marshaler. func (Subscription) MarshalXML(e *xml.Encoder, _ xml.StartElement) error { … } // UnmarshalXML implements xml.Unmarshaler. func (*Subscription) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error { … } ``` -------------------------------- ### Send Raw XML Tokens Source: https://github.com/mellium/xmpp/blob/main/docs/overview.md Utilize Send and SendElement for copying token readers directly to the output stream. This is useful when you have pre-marshaled XML tokens. ```go // Send copies a token reader to the output stream. func (s *Session) Send(ctx context.Context, r xmlstream.TokenReader) error // SendElement copies a token reader to the output stream with a specific start element. func (s *Session) SendElement(ctx context.Context, r xmlstream.TokenReader, start xml.StartElement) error ``` -------------------------------- ### IQHandlerFunc HandleIQ Method Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md The HandleIQ method for IQHandlerFunc calls the wrapped function. This allows functions to satisfy the IQHandler interface. ```go func (f IQHandlerFunc) HandleIQ(iq stanza.IQ, t xmlstream.TokenReadEncoder, start *xml.StartElement) error HandleIQ calls f(iq, t, start). ``` -------------------------------- ### Define Single XML Namespace Constant Source: https://github.com/mellium/xmpp/blob/main/docs/extensions.md Export a single XML namespace used by the package as a constant named NS for convenience. ```go // The XML namespace used by this package, provided as a convenience. const NS = `urn:xmpp:mam:2` ``` -------------------------------- ### MAM Query Execution (Asynchronous Iterator) Source: https://github.com/mellium/xmpp/blob/main/design/110_mam.md Initiates a MAM query and returns an iterator to process responses as they arrive. This method allows for asynchronous handling of archive results, but requires careful management to avoid blocking the stream. ```go // Get requests history just like the Query function, except that it associates // responses to the original query and allows the user to iterate through them // as they come in. // // Unlike most iterators, archive history may arrive interspersed with other // traffic, causing the Iter to block waiting for the next response from the // archive. // Care should be taken not to block processing of the stream. // When the iter is closed if any subsequent responses are received they are // sent to the normal serve handler for processing. func (Handler) Get(ctx context.Context, q Query) *Iter ``` -------------------------------- ### Register IQ Stanza Handler Option Source: https://github.com/mellium/xmpp/blob/main/design/25_stanzamux.md Returns an option that matches IQ stanzas by type and payload name. This is used for registering specific handlers with the ServeMux. ```go func IQ(typ stanza.IQType, payload xml.Name, h IQHandler) Option ``` -------------------------------- ### MAM Handler Registration and Message Handling Source: https://github.com/mellium/xmpp/blob/main/design/110_mam.md Provides methods for registering a handler to process incoming archive responses and for handling individual messages within those responses. Use Handle to register your handler. ```go // Handle returns an option that registers a Handler for archive responses. func Handle(h *Handler) mux.Option // Handler listens for incoming responses from an archive and matches them to // outgoing requests sent with Get or GetIQ. type Handler struct{} // HandleMessage implements mux.MessageHandler. func (h *Handler) HandleMessage(msg stanza.Message, t xmlstream.TokenReadEncoder) error {} ``` -------------------------------- ### IQOption Type Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md A function type used to configure an IQMux. Options modify the behavior of the IQMux upon creation or registration. ```go type IQOption func(m *IQMux) IQOption configures an IQMux. ``` -------------------------------- ### IBB Handler OpenMessage Method Source: https://github.com/mellium/xmpp/blob/main/design/19_ibb.md Initiates a new IBB stream using message stanzas as the carrier. Prefer Open for general use. ```go func (h *Handler) OpenMessage(ctx context.Context, s *xmpp.Session, to jid.JID, blockSize uint16) (*Conn, error) OpenMessage attempts to create a new IBB stream on the provided session using messages as the carrier stanza. Most users should call Open instead. ``` -------------------------------- ### Define XMPP Handler Interface Source: https://github.com/mellium/xmpp/blob/main/docs/overview.md Implement this interface to process incoming XMPP stanzas and other XML elements. The Serve method decodes tokens and delegates handling to a single Handler. ```go package xmpp import ( "encoding/xml" "mellium.im/xmlstream" ) // A Handler triggers events or responds to incoming elements in an XML stream. type Handler interface { HandleXMPP(t xmlstream.TokenReadEncoder, start *xml.StartElement) error } ``` -------------------------------- ### ErrorIQ Option Source: https://github.com/mellium/xmpp/blob/main/design/18_iqmux.md Creates an IQOption to handle IQ stanzas of type 'error' with a wildcard XML name. Useful because error IQs can have unpredictable child elements. ```go func ErrorIQ(h IQHandler) IQOption ErrorIQ is a shortcut for HandleIQ with the type set to "error" and a wildcard XML name. This differs from the other IQ types because error IQs may contain one or more child elements and we cannot guarantee the order of child elements and therefore won't know which element to match on. Instead it is normally wise to register a handler for all error type IQs and then skip or handle unnecessary payloads until we find the error itself. ``` -------------------------------- ### PubSub Event Handler Interface Source: https://github.com/mellium/xmpp/blob/main/design/292_pubsub_notify.md Defines the `Handler` interface for responding to pubsub events and the `HandlerFunc` type for adapting ordinary functions to this interface. ```go // Handler responds to pubsub events. type Handler interface { HandleEvent(stanza.Message, pubsub.Iter) error } // The HandlerFunc type is an adapter to allow the use of ordinary functions as // event handlers. // If f is a function with the appropriate signature, EventHandlerFunc(f) is a // Handler that calls f. type HandlerFunc func(stanza.Message, pubsub.Iter) error // HandleEvent calls f(msg, iter). func (f HandlerFunc) HandleEvent(msg stanza.Message, iter pubsub.Iter) error { … } ``` -------------------------------- ### Using a Roster Item Iterator Source: https://github.com/mellium/xmpp/blob/main/docs/extensions.md Demonstrates how to use a roster item iterator in a for loop to process roster items lazily. It includes error handling and ensures the iterator is closed. ```go iter := roster.Fetch(context.TODO(), session) defer iter.Close() for iter.Next() { item := iter.Item() // Do something with the roster item } if iter.Err() != nil { // Handle errors } ``` -------------------------------- ### Send IQ Stanzas with Reply Handling Source: https://github.com/mellium/xmpp/blob/main/docs/overview.md SendIQ and SendIQElement are specialized methods for sending IQ stanzas, which require a reply in XMPP. These methods block until a reply is received, allowing for synchronous-style asynchronous code. ```go // SendIQ sends an IQ stanza and waits for a reply. func (s *Session) SendIQ(ctx context.Context, r xmlstream.TokenReader) (xmlstream.TokenReadCloser, error) // SendIQElement sends an IQ stanza with a specific payload and IQ stanza, then waits for a reply. func (s *Session) SendIQElement(ctx context.Context, payload xmlstream.TokenReader, iq stanza.IQ) (xmlstream.TokenReadCloser, error) ``` -------------------------------- ### Registering a Handler for Entity Time Requests Source: https://github.com/mellium/xmpp/blob/main/docs/extensions.md This option registers a Handler for entity time requests. It is used to configure the mux.ServeMux. ```go // Handle returns an option that registers a Handler for entity time requests. func Handle(h Handler) mux.Option { return mux.IQ(stanza.GetIQ, xml.Name{Local: "time", Space: NS}, h) } ``` -------------------------------- ### SessionState Constants Source: https://github.com/mellium/xmpp/blob/main/docs/overview.md Defines bit flags for session state, used to determine feature negotiation order and requirements. These constants represent the security status, authentication status, negotiation completion, and session initiation origin. ```go const ( // Secure indicates that the underlying connection has been secured. For // instance, after STARTTLS has been performed or if a pre-secured // connection is being used such as websockets over HTTPS. Secure SessionState = 1 << iota // Authn indicates that the session has been authenticated (probably with // SASL). Authn // Ready indicates that the session is fully negotiated and that XMPP // stanzas may be sent and received. Ready // Received indicates that the session was initiated by a foreign entity. Received … ) ``` -------------------------------- ### Verify Git Tag Source: https://github.com/mellium/xmpp/blob/main/docs/SECURITY.md Verify the integrity of a signed Git tag using GPG. Ensure you have first received the public GPG key. ```bash gpg --recv-keys 82214D7FB54DC9A3BC0CDAE116D5138E52B849B3 git verify-tag v0.21.4 ``` -------------------------------- ### IBB Handler HandleXMPP Method Source: https://github.com/mellium/xmpp/blob/main/design/19_ibb.md Implements the xmpp.Handler interface for handling XMPP tokens and elements. ```go func (h *Handler) HandleXMPP(t xmlstream.TokenReadEncoder, start *xml.StartElement) error HandleXMPP implements xmpp.Handler. ``` -------------------------------- ### Advertising Hash Support Source: https://github.com/mellium/xmpp/blob/main/design/266_crypto.md Provides a function to generate an iterator for advertising supported hash functions during XMPP service discovery. It ensures only available hashes are advertised. ```go // Features returns an iter that can be registered against a mux to // advertise support for the hash list. // The iter will return an error for any hashes that are not available in // the binary. func Features(h ...Hash) info.FeatureIter { … } ``` -------------------------------- ### Configuring Git to Automatically Sign Commits Source: https://github.com/mellium/xmpp/blob/main/docs/CONTRIBUTING.md To automatically sign all new commits, configure Git to use a commit message template file that includes your signature. ```shell echo -en "\n\nSigned-off-by: Andrew Aguecheek " \ > ~/.config/git/gitmessage ``` ```git git config commit.template ~/.config/git/gitmessage ``` -------------------------------- ### Subscription Management Source: https://github.com/mellium/xmpp/blob/main/design/292_pubsub_notify.md Methods for subscribing to and unsubscribing from pubsub nodes. ```APIDOC ## Subscriptions Methods ### Subscribe ```go func (*Subscriptions) Subscribe(ctx context.Context, to jid.JID, session *xmpp.Session, ns string, h Handler) (Subscription, error) ``` Creates a new subscription to a namespace. The namespace should not include the `+notify` suffix. If a subscription already exists for the namespace, Subscribe is a noop. ### SubscribeFunc ```go func (*Subscriptions) SubscribeFunc(ctx context.Context, to jid.JID, session *xmpp.Session, ns string, h Handler) (Subscription, error) ``` Similar to `Subscribe`, but accepts a `HandlerFunc`. ### Unsubscribe ```go func (*Subscriptions) Unsubscribe(ctx context.Context, ns string) error ``` Removes a subscription and stops handling events. Sends the unsubscribe stanza regardless of whether a subscription is registered. ``` -------------------------------- ### Prosody Config Type Definition Source: https://github.com/mellium/xmpp/blob/main/design/42_integration_testing.md Defines the `Config` type used for configuring Prosody instances, including fields for administrators and virtual hosts. ```go // Config contains options that can be written to a Prosody config file. type Config { Admins []string VHosts []string … } ``` -------------------------------- ### StreamConfig for Default Negotiator Source: https://github.com/mellium/xmpp/blob/main/docs/overview.md Configuration struct for the default XMPP session negotiator. It allows setting stream language, features, and optional input/output stream copying for debugging. ```go // StreamConfig contains options for configuring the default Negotiator. type StreamConfig struct { // The native language of the stream. Lang string // A list of stream features to attempt to negotiate. Features []StreamFeature // If set a copy of any reads from the session will be written to TeeIn and // any writes to the session will be written to TeeOut (similar to the tee(1) // command). // This can be used to build an "XML console", but users should be careful // since this bypasses TLS and could expose passwords and other sensitive // data. TeeIn, TeeOut io.Writer } ``` -------------------------------- ### Cmd Type Definition Source: https://github.com/mellium/xmpp/blob/main/design/42_integration_testing.md Defines the `Cmd` type, which represents an external command being prepared or run, embedding `exec.Cmd` and adding custom fields. ```go type Cmd struct { *exec.Cmd } ``` -------------------------------- ### MAM Query Execution (Synchronous) Source: https://github.com/mellium/xmpp/blob/main/design/110_mam.md Sends a MAM query and blocks until all response messages are received and processed. This is suitable for synchronous retrieval of archive history. ```go // Get can be called to send a query where the responses should be handled by a // user defined handler. // It will block until all messages sent in response have been received and // processed. func Get(ctx context.Context, q Query) error {} ``` -------------------------------- ### Access Raw Token Writer Source: https://github.com/mellium/xmpp/blob/main/docs/overview.md Obtain a TokenWriteFlushCloser using TokenWriter to directly write XML tokens to the session's output stream. This provides low-level control over the stream. ```go // TokenWriter returns a writer for raw XML tokens. func (s *Session) TokenWriter() xmlstream.TokenWriteFlushCloser ``` -------------------------------- ### Subscription State and Type Definitions Source: https://github.com/mellium/xmpp/blob/main/design/292_pubsub_notify.md Defines the `SubType` enum for subscription states (None, Subscribed, Unconfigured, Pending) and associated methods for unmarshaling and marshaling XML attributes. ```go // SubType represents the state of a particular subscription. type SubType uint8 func (SubType) String() string { … } // UnmarshalXMLAttr satisfies xml.UnmarshalerAttr. func (*SubType) UnmarshalXMLAttr(attr xml.Attr) error { … } // MarshalXMLAttr satisfies xml.MarshalerAttr. func (s *SubType) MarshalXMLAttr(name xml.Name) (xml.Attr, error) { … } // A list of possible subscription types. const ( SubNone SubType = iota // none SubSubscribed // subscribed SubUnconfigured // unconfigured SubPending // pending ) ``` -------------------------------- ### StreamFeature Function Source: https://github.com/mellium/xmpp/blob/main/design/171_caps.md Retrieves entity caps information advertised by the server during initial connection. Returns ok=false if the ServerCaps feature was not used or no caps were advertised. ```go // StreamFeature returns any entity caps information advertised by the server // when we first connected. // If the ServerCaps feature was not used during the connection or no entity // caps was advertised when connecting, ok will be false. func StreamFeature(s *xmpp.Session) (c Caps, ok bool) { … } ``` -------------------------------- ### IBB Conn Size Method Source: https://github.com/mellium/xmpp/blob/main/design/19_ibb.md Returns the blocksize used for buffering writes to the IBB stream. ```go func (c *Conn) Size() int Size returns the blocksize for the underlying buffer when writing to the IBB stream. ```