connector

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Feb 24, 2025 License: Apache-2.0 Imports: 41 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	HeaderWopiLock              string = "X-WOPI-Lock"
	HeaderWopiOldLock           string = "X-WOPI-OldLock"
	HeaderWopiLockFailureReason string = "X-WOPI-LockFailureReason"
	HeaderWopiST                string = "X-WOPI-SuggestedTarget"
	HeaderWopiRT                string = "X-WOPI-RelativeTarget"
	HeaderWopiOverwriteRT       string = "X-WOPI-OverwriteRelativeTarget"
	HeaderWopiSize              string = "X-WOPI-Size"
	HeaderWopiValidRT           string = "X-WOPI-ValidRelativeTarget"
	HeaderWopiRequestedName     string = "X-WOPI-RequestedName"
	HeaderContentLength         string = "Content-Length"
	HeaderContentType           string = "Content-Type"
	HeaderWopiVersion           string = "X-WOPI-ItemVersion"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Connector 

type Connector struct {
	// contains filtered or unexported fields
}

Connector will implement the WOPI operations. For convenience, the connector splits the operations based on the WOPI endpoints, so you'll need to get the specific connector first.

Available endpoints: * "Files" -> GetFileConnector() * "File contents" -> GetContentConnector()

Other endpoints aren't available for now.

func NewConnector 

func NewConnector(fc FileConnectorService, cc ContentConnectorService) *Connector

NewConnector creates a new connector

func (*Connector) GetContentConnector 

func (c *Connector) GetContentConnector() ContentConnectorService

GetContentConnector gets the content connector service associated to this connector

func (*Connector) GetFileConnector 

func (c *Connector) GetFileConnector() FileConnectorService

GetFileConnector gets the file connector service associated to this connector

type ConnectorError 

type ConnectorError struct {
	HttpCodeOut int
	Msg         string
}

ConnectorError defines an error in the connector. It contains an error code and a message. For convenience, the error code can be used as HTTP error code, although the connector shouldn't know anything about HTTP.

func NewConnectorError 

func NewConnectorError(code int, msg string) *ConnectorError

NewConnectorError creates a new connector error using the provided parameters

func (*ConnectorError) Error 

func (e *ConnectorError) Error() string

Error gets the error message

type ConnectorResponse 

type ConnectorResponse struct {
	Status  int
	Headers map[string]string
	Body    interface{}
}

ConnectorResponse represent a response from the FileConnectorService. The ConnectorResponse is oriented to HTTP, so it has the Status, Headers and Body that the actual HTTP response should have. This includes HTTP errors with status 4xx and 5xx, which will also represent some error conditions for the FileConnectorService. Note that the Body is expected to be JSON-encoded outside before sending.

func NewResponse 

func NewResponse(status int) *ConnectorResponse

NewResponse creates a new ConnectorResponse with just the specified status. Headers and Body will be nil

func NewResponseLockConflict 

func NewResponseLockConflict(lockID string, lockFailureReason string) *ConnectorResponse

NewResponseLockConflict creates a new ConnectorResponse with the status 409 and the "X-WOPI-Lock" header having the value in the lockID parameter.

This is used for conflict responses where the current lock id needs to be returned, although the `GetLock` method also uses this method for a successful response (with the lock id included) The lockFailureReason parameter will be included in the "X-WOPI-LockFailureReason".

func NewResponseSuccessBody 

func NewResponseSuccessBody(body interface{}) *ConnectorResponse

NewResponseSuccessBody creates a new ConnectorResponse with a fixed 200 (success) status and the specified body. The headers will be nil.

This is used for the `CheckFileInfo` method in order to return the fileinfo

func NewResponseSuccessBodyName 

func NewResponseSuccessBodyName(name string) *ConnectorResponse

NewResponseSuccessBodyName creates a new ConnectorResponse with a fixed 200 (success) status and a "map[string]interface{}" body. The body will contain a "Name" key with the supplied name as value.

This is used for the `RenameFile` method in order to return the final name of the renamed file if the operation is successful

func NewResponseSuccessBodyNameUrl 

func NewResponseSuccessBodyNameUrl(name, url string, hostEditURL string, hostViewURL string) *ConnectorResponse

NewResponseSuccessBodyNameUrl creates a new ConnectorResponse with a fixed 200 (success) status and a "map[string]interface{}" body. The body will contain "Name" and "Url" keys with their respective suplied values

This is used in the `PutRelativeFile` methods (both suggested and relative).

func NewResponseWithLock 

func NewResponseWithLock(status int, lockID string) *ConnectorResponse

NewResponse creates a new ConnectorResponse with the specified status and the "X-WOPI-Lock" header having the value in the lockID parameter.

This is usually used for conflict responses where the current lock id needs to be returned, although the `GetLock` method also uses this method for a successful response (with the lock id included)

func NewResponseWithVersion 

func NewResponseWithVersion(mtime *types.Timestamp) *ConnectorResponse

NewResponseWithVersion creates a new ConnectorResponse with the specified status and the "X-WOPI-ItemVersion" header having the value in the mtime parameter.

func NewResponseWithVersionAndLock 

func NewResponseWithVersionAndLock(status int, mtime *types.Timestamp, lockID string) *ConnectorResponse

NewResponseWithVersionAndLock creates a new ConnectorResponse with the specified status and the "X-WOPI-ItemVersion" header and the "X-WOPI-Lock" header having the values in the mtime and lockID parameters.

type ConnectorService 

type ConnectorService interface {
	GetFileConnector() FileConnectorService
	GetContentConnector() ContentConnectorService
}

ConnectorService is the interface to implement the WOPI operations. They're divided into multiple endpoints. The IFileConnector will implement the "File" endpoint The IContentConnector will implement the "File content" endpoint

type ContentConnector 

type ContentConnector struct {
	// contains filtered or unexported fields
}

ContentConnector implements the "File contents" endpoint. Basically, the ContentConnector handles downloads (GetFile) and uploads (PutFile) Note that operations might return any kind of error, not just ConnectorError

func NewContentConnector 

func NewContentConnector(gws pool.Selectable[gatewayv1beta1.GatewayAPIClient], cfg *config.Config) *ContentConnector

NewContentConnector creates a new content connector

func (*ContentConnector) GetFile 

func (c *ContentConnector) GetFile(ctx context.Context, w http.ResponseWriter) error

GetFile downloads the file from the storage https://docs.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/getfile

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

The contents of the file will be written directly into the http Response writer passed as parameter. Be aware that the body of the response will be written during the execution of this method. Any further modifications to the response headers or body will be ignored.

func (*ContentConnector) PutFile 

func (c *ContentConnector) PutFile(ctx context.Context, stream io.Reader, streamLength int64, lockID string) (*ConnectorResponse, error)

PutFile uploads the file to the storage https://docs.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/putfile

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

The contents of the file will be read from the stream. The full stream length must be provided in order to upload the file.

A lock ID must be provided for the upload (which must match the lock in the file). The only case where an empty lock ID can be used is if the target file has 0 size.

This method will return the lock ID that should be returned in case of a conflict, otherwise it will return an empty string. This means that if the method returns a ConnectorError with code 409, the returned string is the lock ID that should be used in the X-WOPI-Lock header. In other error cases or if the method is successful, an empty string will be returned (check for err != nil to know if something went wrong)

On success, the method will return the new mtime of the file

type ContentConnectorService 

type ContentConnectorService interface {
	// GetFile downloads the file and write its contents in the provider writer
	GetFile(ctx context.Context, w http.ResponseWriter) error
	// PutFile uploads the stream up to the stream length. The file should be
	// locked beforehand, so the lockID needs to be provided.
	// The current lockID will be returned ONLY if a conflict happens (the file is
	// locked with a different lockID)
	PutFile(ctx context.Context, stream io.Reader, streamLength int64, lockID string) (*ConnectorResponse, error)
}

ContentConnectorService is the interface to implement the "File contents" endpoint. Basically upload and download contents. All operations need a context containing a WOPI context and, optionally, a zerolog logger. Target file is within the WOPI context

type FileConnector 

type FileConnector struct {
	// contains filtered or unexported fields
}

FileConnector implements the "File" endpoint. Currently, it handles file locks and getting the file info. Note that operations might return any kind of error, not just ConnectorError

func NewFileConnector 

func NewFileConnector(gws pool.Selectable[gatewayv1beta1.GatewayAPIClient], cfg *config.Config, st microstore.Store) *FileConnector

NewFileConnector creates a new file connector

func (*FileConnector) CheckFileInfo 

func (f *FileConnector) CheckFileInfo(ctx context.Context) (*ConnectorResponse, error)

CheckFileInfo returns information about the requested file and capabilities of the wopi server https://docs.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/checkfileinfo

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

If the operation is successful, a "FileInfo" instance will be returned, otherwise the "FileInfo" will be empty and an error will be returned.

func (*FileConnector) DeleteFile 

func (f *FileConnector) DeleteFile(ctx context.Context, lockID string) (*ConnectorResponse, error)

DeleteFile will delete the requested file https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/deletefile

The lock isn't part of the documentation, but it might be possible to delete a file as long as you have the lock. In addition, we'll need to return the lock if there is a conflict.

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

Note that this method isn't required and it's likely used just for the WOPI validator

func (*FileConnector) GetLock 

func (f *FileConnector) GetLock(ctx context.Context) (*ConnectorResponse, error)

GetLock returns a lock or an empty string if no lock exists https://docs.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/getlock

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

The lock ID applied to the file reference in the context will be returned (if any). An error will be returned if something goes wrong. The error could be a ConnectorError

func (*FileConnector) Lock 

func (f *FileConnector) Lock(ctx context.Context, lockID, oldLockID string) (*ConnectorResponse, error)

Lock returns a WOPI lock or performs an unlock and relock https://docs.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/lock https://docs.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/unlockandrelock

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

Lock the file reference contained in the context with the provided lockID. The oldLockID is only used for the "unlock and relock" operation. The "lock" operation doesn't use the oldLockID and needs to be empty in this case.

For the "lock" operation, if the operation is successful, an empty lock id will be returned without any error. In case of conflict, the current lock id will be returned along with a 409 ConnectorError. For any other error, the method will return an empty lock id.

For the "unlock and relock" operation, the behavior will be the same.

On success, the mtime of the file will be returned in the X-Wopi-Version header.

func (*FileConnector) PutRelativeFileRelative 

func (f *FileConnector) PutRelativeFileRelative(ctx context.Context, ccs ContentConnectorService, stream io.Reader, streamLength int64, target string) (*ConnectorResponse, error)

PutRelativeFileRelative upload a file using the provided target name https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/putrelativefile

The PutRelativeFile have 2 variants based on the "X-WOPI-SuggestedTarget" and "X-WOPI-RelativeTarget" headers. This method only implements the second, so this method must be used only if the "X-WOPI-RelativeTarget" is present.

The "target" filename must be UTF8-encoded. The conversion between UTF7 and UTF8 must happen outside this function.

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

Since the method involves uploading a file to a location, it will use the provided ContentConnectorService to upload the stream. Note that the associated wopicontext is modified in order to point to the right location before the upload (it shouldn't matter because we'll work on a copy).

As per documentation, this method will try to upload the provided stream using the provided name. The filename won't be changed. Since the upload won't use any lock, the upload will fail if the target file already exists and it isn't empty. This means that, this method can only generate new files.

func (*FileConnector) PutRelativeFileSuggested 

func (f *FileConnector) PutRelativeFileSuggested(ctx context.Context, ccs ContentConnectorService, stream io.Reader, streamLength int64, target string) (*ConnectorResponse, error)

PutRelativeFileSuggested upload a file using the suggested target name https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/putrelativefile

The PutRelativeFile have 2 variants based on the "X-WOPI-SuggestedTarget" and "X-WOPI-RelativeTarget" headers. This method only implements the first, so this method must be used only if the "X-WOPI-SuggestedTarget" is present.

The "target" filename must be UTF8-encoded. The conversion between UTF7 and UTF8 must happen outside this function.

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

Since the method involves uploading a file to a location, it will use the provided ContentConnectorService to upload the stream. Note that the associated wopicontext is modified in order to point to the right location before the upload (it shouldn't matter because we'll work on a copy).

As per documentation, this method will try to upload the provided stream using the suggested name. If the upload fails, we'll try using a different name. This new name will be generated by prefixing a random string to the suggested name. Since the upload won't use any lock, the upload will fail if the target file already exists and it isn't empty. This means that, this method can only generate new files.

func (*FileConnector) RefreshLock 

func (f *FileConnector) RefreshLock(ctx context.Context, lockID string) (*ConnectorResponse, error)

RefreshLock refreshes a provided lock for 30 minutes https://docs.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/refreshlock

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

If the operation is successful, an empty lock id will be returned without any error. In case of conflict, the current lock id will be returned along with a 409 ConnectorError. For any other error, the method will return an empty lock id. The conflict happens if the provided lockID doesn't match the one actually applied in the target file.

On success, the mtime of the file will be returned in the X-Wopi-Version header.

func (*FileConnector) RenameFile 

func (f *FileConnector) RenameFile(ctx context.Context, lockID, target string) (*ConnectorResponse, error)

RenameFile will rename the requested file https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/renamefile

The "target" filename must be UTF8-encoded. The conversion between UTF7 and UTF8 must happen outside this function.

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

The method will return the final target name as first return value (target is just a suggestion, so it could have changed) and the actual lockId in case of conflict as second return value, otherwise the returned lockId will be empty.

func (*FileConnector) UnLock 

func (f *FileConnector) UnLock(ctx context.Context, lockID string) (*ConnectorResponse, error)

UnLock removes a given lock from a file https://docs.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/files/unlock

The context MUST have a WOPI context, otherwise an error will be returned. You can pass a pre-configured zerologger instance through the context that will be used to log messages.

If the operation is successful, an empty lock id will be returned without any error. In case of conflict, the current lock id will be returned along with a 409 ConnectorError. For any other error, the method will return an empty lock id. The conflict happens if the provided lockID doesn't match the one actually applied in the target file.

On success, the mtime of the file will be returned in the X-Wopi-Version header.

type FileConnectorService 

type FileConnectorService interface {
	// GetLock will return the lockID present in the target file.
	GetLock(ctx context.Context) (*ConnectorResponse, error)
	// Lock will lock the target file with the provided lockID. If the oldLockID
	// is provided (not empty), the method will perform an unlockAndRelock
	// operation (unlock the file with the oldLockID and immediately relock
	// the file with the new lockID).
	// The current lockID will be returned if a conflict happens
	Lock(ctx context.Context, lockID, oldLockID string) (*ConnectorResponse, error)
	// RefreshLock will extend the lock time 30 minutes. The current lockID
	// needs to be provided.
	// The current lockID will be returned if a conflict happens
	RefreshLock(ctx context.Context, lockID string) (*ConnectorResponse, error)
	// UnLock will unlock the target file. The current lockID needs to be
	// provided.
	// The current lockID will be returned if a conflict happens
	UnLock(ctx context.Context, lockID string) (*ConnectorResponse, error)
	// CheckFileInfo will return the file information of the target file
	CheckFileInfo(ctx context.Context) (*ConnectorResponse, error)
	// PutRelativeFileSuggested will create a new file based on the contents of the
	// current file. Target is the filename that will be used for this
	// new file.
	// This implements the "suggested" code flow for the PutRelativeFile endpoint.
	// Since we need to upload contents, it will be done through the provided
	// The target must be UTF8-encoded.
	// ContentConnectorService
	PutRelativeFileSuggested(ctx context.Context, ccs ContentConnectorService, stream io.Reader, streamLength int64, target string) (*ConnectorResponse, error)
	// PutRelativeFileRelative will create a new file based on the contents of the
	// current file. Target is the filename that will be used for this
	// new file.
	// This implements the "relative" code flow for the PutRelativeFile endpoint.
	// The required headers that could need to be sent through HTTP will also
	// be returned if needed.
	// The target must be UTF8-encoded.
	// Since we need to upload contents, it will be done through the provided
	// ContentConnectorService
	PutRelativeFileRelative(ctx context.Context, ccs ContentConnectorService, stream io.Reader, streamLength int64, target string) (*ConnectorResponse, error)
	// DeleteFile will delete the provided file in the context. Although
	// not documented, a lockID can be used to try to delete a locked file
	// assuming the lock matches.
	// The current lockID will be returned if the file is locked.
	DeleteFile(ctx context.Context, lockID string) (*ConnectorResponse, error)
	// RenameFile will rename the provided file in the context to the requested
	// filename. The filename must be UTF8-encoded.
	// In case of conflict, this method will return the actual lockId in
	// the file as second return value.
	RenameFile(ctx context.Context, lockID, target string) (*ConnectorResponse, error)
}

FileConnectorService is the interface to implement the "Files" endpoint. Basically lock operations on the file plus the CheckFileInfo. All operations need a context containing a WOPI context and, optionally, a zerolog logger. Target file is within the WOPI context

type HttpAdapter 

type HttpAdapter struct {
	// contains filtered or unexported fields
}

HttpAdapter will adapt the responses from the connector to HTTP.

The adapter will use the request's context for the connector operations, this means that the request MUST have a valid WOPI context and a pre-configured logger. This should have been prepared in the routing.

All operations are expected to follow the definitions found in https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/endpoints

func NewHttpAdapter 

func NewHttpAdapter(gws pool.Selectable[gatewayv1beta1.GatewayAPIClient], cfg *config.Config, st microstore.Store) *HttpAdapter

NewHttpAdapter will create a new HTTP adapter. A new connector using the provided gateway API client and configuration will be used in the adapter

func NewHttpAdapterWithConnector 

func NewHttpAdapterWithConnector(con ConnectorService, l locks.LockParser) *HttpAdapter

NewHttpAdapterWithConnector will create a new HTTP adapter that will use the provided connector service

func (*HttpAdapter) CheckFileInfo 

func (h *HttpAdapter) CheckFileInfo(w http.ResponseWriter, r *http.Request)

CheckFileInfo will retrieve the information of the file in json format Only the request's context is needed in order to extract the WOPI context. The operation's response will be sent through the response writer and the headers according to the spec

func (*HttpAdapter) DeleteFile 

func (h *HttpAdapter) DeleteFile(w http.ResponseWriter, r *http.Request)

DeleteFile will delete the provided file. If the file is locked and can't be deleted, a 409 conflict error will be returned with its corresponding lock.

func (*HttpAdapter) GetFile 

func (h *HttpAdapter) GetFile(w http.ResponseWriter, r *http.Request)

GetFile will download the file Only the request's context is needed in order to extract the WOPI context. The file's content will be written in the response writer

func (*HttpAdapter) GetLock 

func (h *HttpAdapter) GetLock(w http.ResponseWriter, r *http.Request)

GetLock adapts the "GetLock" operation for WOPI. Only the request's context is needed in order to extract the WOPI context. The operation's response will be sent through the response writer and the headers according to the spec

func (*HttpAdapter) Lock 

func (h *HttpAdapter) Lock(w http.ResponseWriter, r *http.Request)

Lock adapts the "Lock" and "UnlockAndRelock" operations for WOPI. The request's context is needed in order to extract the WOPI context. In addition, the "X-WOPI-Lock" and "X-WOPI-OldLock" headers might be needed" (check spec) The operation's response will be sent through the response writer and the headers according to the spec

func (*HttpAdapter) PutFile 

func (h *HttpAdapter) PutFile(w http.ResponseWriter, r *http.Request)

PutFile will upload the file The request's context and its body are needed (content length is also needed) The operation's response will be sent through the response writer and the headers according to the spec

func (*HttpAdapter) PutRelativeFile 

func (h *HttpAdapter) PutRelativeFile(w http.ResponseWriter, r *http.Request)

PutRelativeFile will upload the file with a specific name. The name might be automatically adjusted depending on the request headers. Note that this method will also send a json body in the response. It has 2 mutually exclusive operation methods that are used based on the provided headers in the request. Note that this method won't used locks (not documented).

The file name must be encoded in utf7. This method will decode the utf7 name into utf8. The utf8 (not utf7) name must have less than 512 bytes, otherwise the request will fail.

func (*HttpAdapter) RefreshLock 

func (h *HttpAdapter) RefreshLock(w http.ResponseWriter, r *http.Request)

RefreshLock adapts the "RefreshLock" operation for WOPI The request's context is needed in order to extract the WOPI context. In addition, the "X-WOPI-Lock" header is needed (check spec). The lock will be refreshed to last another 30 minutes. The value is hardcoded The operation's response will be sent through the response writer and the headers according to the spec

func (*HttpAdapter) RenameFile 

func (h *HttpAdapter) RenameFile(w http.ResponseWriter, r *http.Request)

RenameFile will rename the file. The name might be automatically adjusted. Note that this method will also send a json body in the response. The adjusted file name will be returned in the body.

The file name must be encoded in utf7. This method will decode the utf7 name into utf8. The utf8 (not utf7) name must have less than 495 bytes, otherwise the request will fail.

func (*HttpAdapter) UnLock 

func (h *HttpAdapter) UnLock(w http.ResponseWriter, r *http.Request)

UnLock adapts the "Unlock" operation for WOPI The request's context is needed in order to extract the WOPI context. In addition, the "X-WOPI-Lock" header is needed (check spec). The operation's response will be sent through the response writer and the headers according to the spec

Source Files

View all Source files

Directories

Path Synopsis

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.