xrpc

package module

v0.0.0-...-5a61ea1 Latest Latest Go to latest Published: May 6, 2025 License: MIT Imports: 9 Imported by: 9

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/reiver/go-xrpc

Links

Open Source Insights

README ¶

go-xrpc

Package xrpc provides an implementation of the XRPC protocol used by BlueSky and its AT-Protocol, for the Go programming language.

Documention

Online documentation, which includes examples, can be found at: http://godoc.org/github.com/reiver/go-xrpc

Explanation

XRPC is a client-server protocol. This package implements both the client-side and the server-side of the protocol.

XRPC has 3 requests types:

executve (called procedure in the XRPC documentation),
query, and
subscribe.

This package provides functions for making each of these requests:

xrpc.Execute()
xrpc.Query()
xrpc.Subscribe()

(See examples to see how to use each.)

An XRPC URL needs to be passed to each of these functions. For example:

const url string = "xrpc://public.api.bsky.app/app.bsky.actor.getProfile?actor=reiver.bsky.social"

err := xrpc.Query(dst, url)

This package (introduces and) supports 2 types of XRPC URLs:

xrpc, and
xrpc-unencrypted.

For example:

xrpc://public.api.bsky.app/app.bsky.actor.getProfile?actor=reiver.bsky.social
xrpc-unencrypted://localhost/app.bsky.actor.getProfile?actor=reiver.bsky.social

Examples

Here is an example of making a 'query' XRPC request:

import "github.com/reiver/go-xrpc"

// ...

var response map[string]any = map[string]any{}

url := "xrpc://public.api.bsky.app/app.bsky.actor.getProfile?actor=reiver.bsky.social"

err := xrpc.Query(&response, url)

XRPC URL Resolution

This package introduces two URL schemes:

xrpc, and
xrpc-unencrypted.

For example:

xrpc://public.api.bsky.app/app.bsky.actor.getProfile?actor=reiver.bsky.social
xrpc-unencrypted://localhost/app.bsky.actor.getProfile?actor=reiver.bsky.social

Behind-the-scenes the scenes, these XRPC URL schemes are resolved to HTTPS, HTTP, WSS, and WS URLs.

MOST DEVELOPERS WHO ARE JUST MAKING XRPC CLIENT REQUESTS DO NOT HAVE TO WORRY ABOUT THE DETAILS OF THE RESOLUTION. IN THE SAME WAY THAT MOST DEVELOPERS DO NOT HAVE TO WORRY ABOUT HOW HTTP URLS ARE RESOLVED TO TCP.

How an XRPC URL gets resolved to an HTTPS, HTTP, WSS, or WS URL, depends on the XRPC request type.

Here are some examples:

XRPC URL	XRPC Request Type	Resolved URL
`xrpc://example.com/app.cherry.fooBar`	`execute`	`https://example.com/xrpc/app.cherry.fooBar`
`xrpc://example.com/app.cherry.fooBar`	`query`	`https://example.com/xrpc/app.cherry.fooBar`
`xrpc://example.com/app.cherry.fooBar`	`subscribe`	`wss://example.com/xrpc/app.cherry.fooBar`
`xrpc-unencrypted://localhost/link.banana.bazQux`	`execute`	`http://localhost/xrpc/link.banana.bazQux`
`xrpc-unencrypted://localhost/link.banana.bazQux`	`query`	`http://localhost/xrpc/link.banana.bazQux`
`xrpc-unencrypted://localhost/link.banana.bazQux`	`subscribe`	`ws://localhost/xrpc/link.banana.bazQux`

These 2 XRPC URLs are passed to the xrpc.Execute(), xrpc.Query(), and xrpc.Subscribe() functions.

Import

To import package xrpc use import code like the follownig:

import "github.com/reiver/go-xrpc"

Installation

To install package xrpc do the following:

GOPROXY=direct go get https://github.com/reiver/go-xrpc

Author

Package xrpc was written by Charles Iliya Krempeaux

Documentation ¶

Index ¶

Constants
func AuthorizedExecute(dst any, bearerToken string, url string, src any) error
func AuthorizedQuery(dst any, bearerToken string, url string) error
func Execute(dst any, url string, src any) error
func Query(dst any, url string) error
func SetUserAgent(value string)
type Iterator
- func Subscribe(url string) (Iterator, error)

Constants ¶

View Source

const (
	RequestTypeExecute   string = "execute" // an alternative name for "procedure" so that all the request-types can be a verb.
	RequestTypeProcedure string = "procedure"
	RequestTypeQuery     string = "query"
	RequestTypeSubscribe string = "subscribe"
)

Variables ¶

This section is empty.

Functions ¶

func AuthorizedExecute ¶

func AuthorizedExecute(dst any, bearerToken string, url string, src any) error

func AuthorizedQuery ¶

func AuthorizedQuery(dst any, bearerToken string, url string) error

func Execute ¶

func Execute(dst any, url string, src any) error

Execute makes an 'execute' XRPC request to the provided URL (passed in 'url'), putting the results into 'dst'.

NOTE that the official Bluesky docs call the 'execute' XRPC request-type 'procedure'. ('execute' was chosen here as it is a verb.)

You can provide Execute with an `https`, `http`, `xrpc`, or `xrpc-unencrypted` URL.

Here is an example usage of calling Execute with an `xrpc` URL:

var response map[string]any = map[string]any{}

src := struct{
	Identifier string `json:"identifier"`
	Password   string `json:"password"`
}{
	Identifier: "joeblow.bsky.social",
	Password:   "password123",
}

url := "xrpc://bsky.social/com.atproto.server.createSession"

err := xrpc.Execute(&response, url, src)

Here is an example usage of calling Execute with an `https` URL:

var response map[string]any = map[string]any{}

src := struct{
	Identifier string `json:"identifier"`
	Password   string `json:"password"`
}{
	Identifier: "joeblow.bsky.social",
	Password:   "password123",
}

url := "https://bsky.social/xrpc/com.atproto.server.createSession"

err := xrpc.Execute(&response, url, src)

func Query ¶

func Query(dst any, url string) error

Query makes a 'query' XRPC request to the provided URL (passed in 'url'), putting the results into 'dst'.

You can provide Query with an `https`, `http`, `xrpc`, or `xrpc-unencrypted` URL.

Here is an example usage of calling Query with an `xrpc` URL:

var response map[string]any = map[string]any{}

url := "xrpc://public.api.bsky.app/app.bsky.actor.getProfile?actor=reiver.bsky.social"

err := xrpc.Query(&response, url)

Here is an example usage of calling Query with an `https` URL:

var response map[string]any = map[string]any{}

url := "https://public.api.bsky.app/xrpc/app.bsky.actor.getProfile?actor=reiver.bsky.social"

err := xrpc.Query(&response, url)

func SetUserAgent ¶

func SetUserAgent(value string)

SetUserAgent sets the User-Agent in XRPC requests.

Types ¶

type Iterator ¶

type Iterator interface {
	Close() error
	Decode(any) error
	Err() error
	Next() bool
}

Iterator represents an iterator.

func Subscribe(url string) (Iterator, error)

Subscribe makes a 'subscribe' XRPC request for the provided XRPC URL in 'url'.

Example usage:

var response map[string]any = map[string]any{}

url = "xrpc://public.api.bsky.app/app.bsky.actor.getProfile?actor=reiver.bsky.social"

err := xrpc.Subscribe(&response, url)

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL