Add doc comments

This commit is contained in:
Elara 2022-12-13 10:49:58 -08:00
parent c1d9a76a7f
commit c19f44c304
3 changed files with 47 additions and 20 deletions

View File

@ -13,16 +13,19 @@ import (
"go.arsenm.dev/go-lemmy/types"
)
// Client is a client for Lemmy's HTTP API
type Client struct {
client *http.Client
baseURL *url.URL
token string
Token string
}
// New creates a new Lemmy client with the default HTTP client.
func New(baseURL string) (*Client, error) {
return NewWithClient(baseURL, http.DefaultClient)
}
// NewWithClient creates a new Lemmy client with the given HTTP client
func NewWithClient(baseURL string, client *http.Client) (*Client, error) {
u, err := url.Parse(baseURL)
if err != nil {
@ -33,6 +36,9 @@ func NewWithClient(baseURL string, client *http.Client) (*Client, error) {
return &Client{baseURL: u, client: client}, nil
}
// Login logs in to Lemmy by sending an HTTP request to the
// login endpoint. It stores the returned token in the client
// for future use.
func (c *Client) Login(ctx context.Context, l types.Login) error {
var lr types.LoginResponse
res, err := c.req(ctx, http.MethodPost, "/user/login", l, &lr)
@ -45,19 +51,12 @@ func (c *Client) Login(ctx context.Context, l types.Login) error {
return err
}
c.token = lr.JWT.MustValue()
c.Token = lr.JWT.MustValue()
return nil
}
func (c *Client) Token() string {
return c.token
}
func (c *Client) SetToken(t string) {
c.token = t
}
// req makes a request to the server
func (c *Client) req(ctx context.Context, method string, path string, data, resp any) (*http.Response, error) {
data = c.setAuth(data)
@ -98,6 +97,9 @@ func (c *Client) req(ctx context.Context, method string, path string, data, resp
return res, nil
}
// getReq makes a get request to the Lemmy server.
// It is separate from req() because it uses query
// parameters rather than a JSON request body.
func (c *Client) getReq(ctx context.Context, method string, path string, data, resp any) (*http.Response, error) {
data = c.setAuth(data)
@ -134,6 +136,7 @@ func (c *Client) getReq(ctx context.Context, method string, path string, data, r
return res, nil
}
// resError returns an error if the given response is an error
func resError(res *http.Response, lr types.LemmyResponse) error {
if lr.Error.IsValid() {
return types.LemmyError{
@ -149,6 +152,11 @@ func resError(res *http.Response, lr types.LemmyResponse) error {
}
}
// setAuth uses reflection to automatically
// set struct fields called Auth of type
// string or types.Optional[string] to the
// authentication token, then returns the
// updated struct
func (c *Client) setAuth(data any) any {
if data == nil {
return data
@ -164,10 +172,10 @@ func (c *Client) setAuth(data any) any {
switch authField.Type().String() {
case "string":
authField.SetString(c.token)
authField.SetString(c.Token)
case "types.Optional[string]":
setMtd := authField.MethodByName("Set")
out := setMtd.Call([]reflect.Value{reflect.ValueOf(c.token)})
out := setMtd.Call([]reflect.Value{reflect.ValueOf(c.Token)})
authField.Set(out[0])
default:
return data

View File

@ -49,7 +49,7 @@ func (c *Client) ChangePassword(ctx context.Context, d types.ChangePassword) (*t
return nil, err
}
c.token = ar.JWT.MustValue()
c.Token = ar.JWT.MustValue()
return ar, nil
}
@ -231,7 +231,7 @@ func (c *Client) PasswordChange(ctx context.Context, d types.PasswordChange) (*t
return nil, err
}
c.token = ar.JWT.MustValue()
c.Token = ar.JWT.MustValue()
return ar, nil
}
@ -263,7 +263,7 @@ func (c *Client) Register(ctx context.Context, d types.Register) (*types.LoginRe
return nil, err
}
c.token = ar.JWT.MustValue()
c.Token = ar.JWT.MustValue()
return ar, nil
}
@ -280,7 +280,7 @@ func (c *Client) SaveUserSettings(ctx context.Context, d types.SaveUserSettings)
return nil, err
}
c.token = ar.JWT.MustValue()
c.Token = ar.JWT.MustValue()
return ar, nil
}

View File

@ -15,14 +15,17 @@ type authData struct {
Auth string `json:"auth"`
}
// WSClient is a client for Lemmy's WebSocket API
type WSClient struct {
conn *websocket.Conn
baseURL *url.URL
respCh chan types.LemmyWebSocketMsg
errCh chan error
token string
Token string
}
// NewWebSocket creates and returns a new WSClient, and
// starts a goroutine to read server responses and errors
func NewWebSocket(baseURL string) (*WSClient, error) {
u, err := url.Parse(baseURL)
if err != nil {
@ -57,6 +60,9 @@ func NewWebSocket(baseURL string) (*WSClient, error) {
return out, nil
}
// Login logs in to Lemmy by sending an HTTP request to the
// login endpoint. It stores the returned token in the client
// for future use.
func (c *WSClient) Login(ctx context.Context, l types.Login) error {
u := &url.URL{}
*u = *c.baseURL
@ -72,10 +78,14 @@ func (c *WSClient) Login(ctx context.Context, l types.Login) error {
if err != nil {
return err
}
c.token = hc.token
c.Token = hc.Token
return nil
}
// Request sends a request to the server. If data is nil,
// the authentication token will be sent instead. If data
// has an Auth field, it will be set to the authentication
// token automatically.
func (c *WSClient) Request(op types.UserOperation, data any) error {
if data == nil {
data = authData{}
@ -94,14 +104,23 @@ func (c *WSClient) Request(op types.UserOperation, data any) error {
})
}
// Responses returns a channel that receives messages from
// Lemmy.
func (c *WSClient) Responses() <-chan types.LemmyWebSocketMsg {
return c.respCh
}
// Errors returns a channel that receives errors
// received while attempting to read responses
func (c *WSClient) Errors() <-chan error {
return c.errCh
}
// setAuth uses reflection to automatically
// set struct fields called Auth of type
// string or types.Optional[string] to the
// authentication token, then returns the
// updated struct
func (c *WSClient) setAuth(data any) any {
val := reflect.New(reflect.TypeOf(data))
val.Elem().Set(reflect.ValueOf(data))
@ -113,10 +132,10 @@ func (c *WSClient) setAuth(data any) any {
switch authField.Type().String() {
case "string":
authField.SetString(c.token)
authField.SetString(c.Token)
case "types.Optional[string]":
setMtd := authField.MethodByName("Set")
out := setMtd.Call([]reflect.Value{reflect.ValueOf(c.token)})
out := setMtd.Call([]reflect.Value{reflect.ValueOf(c.Token)})
authField.Set(out[0])
default:
return data