feat: support Remember Me for prolonging session validity on user/pass authentication (#52)

2025-03-16 11:48:44 +01:00
parent 473cd3f1ed
commit 873818ddac
4 changed files with 182 additions and 10 deletions
--- a/docs/file_uploads.md
+++ b/docs/file_uploads.md
@@ -0,0 +1,149 @@
+# File Uploads in go-unifi
+
+This document describes how to use the file upload functionality in the go-unifi client.
+
+## Overview
+
+The go-unifi client provides two methods for uploading files to the UniFi controller:
+
+1. `UploadFile` - Upload a file from a file path on disk
+2. `UploadFileFromReader` - Upload a file from an `io.Reader` (e.g., from memory, network stream, etc.)
+
+Both methods use the `multipart/form-data` format for file uploads, which is required by the UniFi controller.
+
+## Examples
+
+### Uploading a file from disk
+
+```go
+package main
+
+import (
+	"context"
+	"log"
+
+	"github.com/filipowm/go-unifi/unifi"
+)
+
+func main() {
+	// Create a client
+	client, err := unifi.NewClient(&unifi.ClientConfig{
+		URL:      "https://your-unifi-controller:8443",
+		User:     "your-username",
+		Password: "your-password",
+	})
+	if err != nil {
+		log.Fatalf("Error creating client: %v", err)
+	}
+
+	// Prepare any additional form fields if needed
+	formFields := map[string]string{
+		"description": "My uploaded file",
+	}
+
+	// Upload the file to the controller
+	var response map[string]interface{} // Adjust this type based on the expected response
+	err = client.UploadFile(
+		context.Background(),
+		"/api/s/default/upload", // The API endpoint to upload to
+		"/path/to/your/file.txt", // Path to the file on disk
+		"file", // Form field name for the file
+		formFields, // Additional form fields
+		&response, // Response structure to capture the result
+	)
+	if err != nil {
+		log.Fatalf("Error uploading file: %v", err)
+	}
+
+	log.Printf("Upload successful: %v", response)
+}
+```
+
+### Uploading a file from memory
+
+```go
+package main
+
+import (
+	"bytes"
+	"context"
+	"log"
+
+	"github.com/paultyng/go-unifi/unifi"
+)
+
+func main() {
+	// Create a client
+	client, err := unifi.NewClient(&unifi.ClientConfig{
+		URL:      "https://your-unifi-controller:8443",
+		User:     "your-username",
+		Password: "your-password",
+	})
+	if err != nil {
+		log.Fatalf("Error creating client: %v", err)
+	}
+
+	// Create file content in memory
+	fileContent := []byte("This is some test content to upload")
+	reader := bytes.NewReader(fileContent)
+
+	// Upload the file from the reader
+	var response map[string]interface{} // Adjust this type based on the expected response
+	err = client.UploadFileFromReader(
+		context.Background(),
+		"/api/s/default/upload", // The API endpoint to upload to
+		reader, // Reader with the file content
+		"myfile.txt", // Filename to use in the upload
+		"file", // Form field name for the file
+		nil, // No additional form fields
+		&response, // Response structure to capture the result
+	)
+	if err != nil {
+		log.Fatalf("Error uploading file: %v", err)
+	}
+
+	log.Printf("Upload successful: %v", response)
+}
+```
+
+## API Reference
+
+### UploadFile
+
+```go
+func (c *client) UploadFile(ctx context.Context, apiPath, filePath, fieldName string, formFields map[string]string, respBody interface{}) error
+```
+
+Uploads a file to the UniFi controller from a file path.
+
+Parameters:
+- `ctx`: The context for the request
+- `apiPath`: The API endpoint path to upload the file to
+- `filePath`: Path to the file on disk
+- `fieldName`: Form field name for the file (defaults to "file" if empty)
+- `formFields`: Additional form fields to include in the upload (can be nil)
+- `respBody`: Structure to decode the response into (can be nil)
+
+### UploadFileFromReader
+
+```go
+func (c *client) UploadFileFromReader(ctx context.Context, apiPath string, reader io.Reader, filename, fieldName string, formFields map[string]string, respBody interface{}) error
+```
+
+Uploads a file to the UniFi controller from an io.Reader.
+
+Parameters:
+- `ctx`: The context for the request
+- `apiPath`: The API endpoint path to upload the file to
+- `reader`: Reader with the file content
+- `filename`: Name of the file to use in the upload
+- `fieldName`: Form field name for the file (defaults to "file" if empty)
+- `formFields`: Additional form fields to include in the upload (can be nil)
+- `respBody`: Structure to decode the response into (can be nil)
+
+## Notes
+
+- These methods use `POST` requests for file uploads
+- The UniFi controller typically expects files to be uploaded with the field name "file", but this can be changed as needed
+- The content type for the request is automatically set to "multipart/form-data" with the correct boundary
+- All existing client features like interceptors, error handling, and request validation are preserved