Skip to content

Commit

Permalink
website: Correct all links
Browse files Browse the repository at this point in the history
  • Loading branch information
Acconut committed Feb 23, 2024
1 parent 21780b7 commit 8632fda
Show file tree
Hide file tree
Showing 11 changed files with 39 additions and 38 deletions.
8 changes: 4 additions & 4 deletions docs/_advanced-topics/hooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ When the process exits with the zero exit code, tusd reads the process' stdout a

The process' stderr is redirected to tusd's stderr and can be used for logging from inside the hook.

An example is available at [/examples/hooks/file](/examples/hooks/file).
An example is available at [/examples/hooks/file]({{ site.baseurl }}/examples/hooks/file).

### HTTP(S) Hooks

Expand Down Expand Up @@ -250,7 +250,7 @@ When the endpoint responds with a non-2XX status code, tusd interprets this as a

When the endpoint responds with a 2XX status code, tusd reads the response body and parses it as a JSON-encoded hook response. This allows the hook to customize the HTTP response, reject and abort uploads.

An example is available at [/examples/hooks/http](/examples/hooks/http).
An example is available at [/examples/hooks/http]({{ site.baseurl }}/examples/hooks/http).

#### Retries

Expand All @@ -273,7 +273,7 @@ $ tusd -hooks-grpc localhost:8081
...
```

The endpoint must implement the hook handler service as specified in [/pkg/hooks/grpc/proto/hook.proto](/pkg/hooks/grpc/proto/hook.proto). Its `InvokeHook` method will be invoked for each triggered events and will be passed the hook request.
The endpoint must implement the hook handler service as specified in [/pkg/hooks/grpc/proto/hook.proto]({{ site.baseurl }}/pkg/hooks/grpc/proto/hook.proto). Its `InvokeHook` method will be invoked for each triggered events and will be passed the hook request.

#### Retries

Expand All @@ -290,7 +290,7 @@ File hooks are an easy way to receive events from tusd, but can induce overhead

Plugin hooks provide a sweet spot between these two worlds. You can create a plugin with any programming language. tusd then loads this plugin by starting it as a standalone process, restarting it if necessary, and communicating with it over local sockets. This system is powered by [go-plugin](https://github.com/hashicorp/go-plugin), which is designed for Go, but provides cross-language support. The approach provides a low-overhead hook handler, which is still able to track state between hooks.

To learn more, have a look at the example at [/examples/hooks/plugin](/examples/hooks/plugin).
To learn more, have a look at the example at [/examples/hooks/plugin]({{ site.baseurl }}/examples/hooks/plugin).

## Common Uses

Expand Down
3 changes: 2 additions & 1 deletion docs/_config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@ title: tusd documentation
description: Reference server implementation in Go of tus, the open protocol for resumable file uploads.
theme: just-the-docs

url: https://just-the-docs.github.io
url: https://tus.github.io
baseurl: /tusd

# Custom color scheme from _sass/color_schemes/custom.scss
color_scheme: custom
Expand Down
4 changes: 2 additions & 2 deletions docs/_getting-started/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,11 @@ $ tusd -disable-termination

## Storage backend

Tusd has been designed with flexible storage backends in mind and can store the received uploads on local disk or various cloud provides (AWS S3, Azure Cloud Storage, and Google Cloud Storage). By default, tusd will store uploads in the directory specified by the `-upload-dir` flag (which defaults to `./data`). Please consult the dedicated [Storage Backends section](/storage-backends/overview/) for details on how to use different storage backend and configure them.
Tusd has been designed with flexible storage backends in mind and can store the received uploads on local disk or various cloud provides (AWS S3, Azure Cloud Storage, and Google Cloud Storage). By default, tusd will store uploads in the directory specified by the `-upload-dir` flag (which defaults to `./data`). Please consult the dedicated [Storage Backends section]({{ site.baseurl }}/storage-backends/overview/) for details on how to use different storage backend and configure them.

## Integrations into applications with hooks

When integrating tusd into an application, it is important to establish a communication channel between tusd and your main application. For this purpose, tusd provides a hook system which triggers user-defined actions when certain events happen, for example when an upload is created or finished. This simple-but-powerful system enables many uses, such as logging, validation, authorization, and post-processing of the uploaded files. Please consult the dedicated [Storage Backends section](/advanced-topics/hooks/) for details on how to use the hook system.
When integrating tusd into an application, it is important to establish a communication channel between tusd and your main application. For this purpose, tusd provides a hook system which triggers user-defined actions when certain events happen, for example when an upload is created or finished. This simple-but-powerful system enables many uses, such as logging, validation, authorization, and post-processing of the uploaded files. Please consult the dedicated [Storage Backends section]({{ site.baseurl }}/advanced-topics/hooks/) for details on how to use the hook system.

## Cross-Origin Resource Sharing (CORS)

Expand Down
4 changes: 2 additions & 2 deletions docs/_getting-started/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,12 @@ The last line from tusd's output indicates the *upload creation URL*:
You can now upload files to: http://[::]:8080/files/
```

This URL can be used by clients to create new uploads. If you want to customize its host, port, or base path, please use the [Network configuration options](/getting-started/configuration/#network-configuration).
This URL can be used by clients to create new uploads. If you want to customize its host, port, or base path, please use the [Network configuration options]({{ site.baseurl }}/getting-started/configuration/#network-configuration).

{: .note }
The `[::]` section in the URL indicates that tusd is accepting connections on all network interfaces, including IPv6. If the client and tusd are on running on the same machine, it can be replaced with `localhost` to form a URL, such as `http://localhost:8080/files/`.

Uploaded files will be stored by default in the directory specified with the `-upload-dir` options. It defaults to the `data` directory in the current working directory. Alternatively, tusd can also store uploads directly on various cloud storage services. Please consult the [Storage Backends section](/storage-backends/overview/) for more details.
Uploaded files will be stored by default in the directory specified with the `-upload-dir` options. It defaults to the `data` directory in the current working directory. Alternatively, tusd can also store uploads directly on various cloud storage services. Please consult the [Storage Backends section]({{ site.baseurl }}/storage-backends/overview/) for more details.

# Connecting clients

Expand Down
2 changes: 1 addition & 1 deletion docs/_storage-backends/aws-s3.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ s3:PutObject

Uploads on S3 are stored using multiple objects:

- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends](/storage-backends/overview/#storage-format).
- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends]({{ site.baseurl }}/storage-backends/overview/#storage-format).
- An [S3 multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) is used to transfer the file piece-by-piece to S3 and reassemble the original file once the upload is finished. It is removed once the upload is finished.
- A file object will contain the uploaded file. It will only be created once the entire upload is finished.
- A temporary object with the `.part` extension may be created when the upload has been paused to store some temporary data which cannot be transferred to the S3 multipart upload due to its small size. Once the upload is resumed, the temporary object will be gone.
Expand Down
2 changes: 1 addition & 1 deletion docs/_storage-backends/azure-blob-storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ $ tusd -azure-storage=my-test-container -azure-blob-access-tier=cool

Uploads are stored using multiple objects:

- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends](/storage-backends/overview/#storage-format).
- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends]({{ site.baseurl }}/storage-backends/overview/#storage-format).
- A file object will contain the uploaded file. Data is appended to the object while the upload is performed.

By default, the objects are stored at the root of the container. For example the objects for the upload ID `abcdef123` will be:
Expand Down
2 changes: 1 addition & 1 deletion docs/_storage-backends/google-cloud-storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The used service account must have the `https://www.googleapis.com/auth/devstora

Uploads are stored using multiple objects:

- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends](/storage-backends/overview/#storage-format).
- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends]({{ site.baseurl }}/storage-backends/overview/#storage-format).
- A file object will contain the uploaded file. Data is appended to the object while the upload is performed.

By default, the objects are stored at the root of the bucket. For example the objects for the upload ID `abcdef123` will be:
Expand Down
4 changes: 2 additions & 2 deletions docs/_storage-backends/local-disk.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@ $ tusd -upload-dir=./uploads
When a new upload is created, for example with the upload ID `abcdef123`, tusd creates two files:

- `./uploads/abcdef123` to hold the file content that is uploaded
- `./uploads/abcdef123.info` to hold [meta information about the upload](/storage-backends/overview/#storage-format)
- `./uploads/abcdef123.info` to hold [meta information about the upload]({{ site.baseurl }}/storage-backends/overview/#storage-format)

## Issues with NFS and shared folders

Tusd maintains [upload locks](/advanced-topics/locks/) on disk to ensure exclusive access to uploads and prevent data corruption. These disk-based locks utilize hard links, which might not supported by older NFS versions or when a folder is shared in a VM using VirtualBox or Vagrant. In these cases, you might get errors like this:
Tusd maintains [upload locks]({{ site.baseurl }}/advanced-topics/locks/) on disk to ensure exclusive access to uploads and prevent data corruption. These disk-based locks utilize hard links, which might not supported by older NFS versions or when a folder is shared in a VM using VirtualBox or Vagrant. In these cases, you might get errors like this:

```
TemporaryErrors (Lockfile created, but doesn't exist)
Expand Down
12 changes: 6 additions & 6 deletions docs/_storage-backends/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,17 @@ nav_order: 1

Tusd can store the uploaded files either on local disk or various cloud storage services:

- [Local disk](/storage-backends/local-disk/)
- [AWS S3 (and S3-compatible services)](/storage-backends/aws-s3/)
- [Azure Blob Storage](/storage-backends/azure-blob-storage/)
- [Google Cloud Storage](/storage-backends/google-cloud-storage/)
- [Local disk]({{ site.baseurl }}/storage-backends/local-disk/)
- [AWS S3 (and S3-compatible services)]({{ site.baseurl }}/storage-backends/aws-s3/)
- [Azure Blob Storage]({{ site.baseurl }}/storage-backends/azure-blob-storage/)
- [Google Cloud Storage]({{ site.baseurl }}/storage-backends/google-cloud-storage/)

## Storage format

While the exact details of how uploaded files are stored depend on the chosen backend, usually two files/objects are created and modified while the upload is progressing:

- An informational file/object with the `.info` extension holds meta information about the upload, such as its size, its metadata, and whether it is used in conjunction with the [concatenation extension](https://tus.io/protocols/resumable-upload#concatenation). The data encoded using [JSON](https://www.json.org/json-en.html). More details can be found in the [documentation of the underlying data structure](https://pkg.go.dev/github.com/tus/[email protected]/pkg/handler#FileInfo).
- Another file/object is created to store the actual file data. It does not have a characteristic extension and its name is either set by the [pre-create hook](/advanced-topics/hooks/) or chosen by the storage backend. Once the upload is finished, it will contain the entire uploaded data. Please note depending on the storage backend (e.g. S3), this file/object might not be present until all data has been transferred.
- Another file/object is created to store the actual file data. It does not have a characteristic extension and its name is either set by the [pre-create hook]({{ site.baseurl }}/advanced-topics/hooks/) or chosen by the storage backend. Once the upload is finished, it will contain the entire uploaded data. Please note depending on the storage backend (e.g. S3), this file/object might not be present until all data has been transferred.

Once an upload is finished, both files/objects are preserved for further processing depending on your application's needs. The informational file/object is useful to retrieve upload metadata and thus not automatically removed by tusd.

Expand All @@ -28,4 +28,4 @@ In a multi-storage setup, multiple storage backends could be configured and dyna

Unfortunately, tusd currently does not support multi-storage setups well. When tusd is started, it will load the configured storage backend, but is not able to dynamically switch between other storage backends.

If you are [using tusd programmatically as a package inside your Go application](/advanced-topics/usage-package/), you can overcome this limitation by dynamically creating multiple tusd handler with different storage backends. Once a request comes in, you need to determine the correct tusd handler for processing and can then route the request accordingly.
If you are [using tusd programmatically as a package inside your Go application]({{ site.baseurl }}/advanced-topics/usage-package/), you can overcome this limitation by dynamically creating multiple tusd handler with different storage backends. Once a request comes in, you need to determine the correct tusd handler for processing and can then route the request accordingly.
12 changes: 6 additions & 6 deletions docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,28 +15,28 @@ nav_order: 2

### How can I access tusd using HTTPS?

Yes, you can achieve this by either running tusd behind a TLS-terminating proxy (such as Nginx or Apache) or configuring tusd to serve HTTPS directly. Details on both approaches are given in the [configuration guide](/getting-started/configuration/#httpstls).
Yes, you can achieve this by either running tusd behind a TLS-terminating proxy (such as Nginx or Apache) or configuring tusd to serve HTTPS directly. Details on both approaches are given in the [configuration guide]({{ site.baseurl }}/getting-started/configuration/#httpstls).

### Can I run tusd behind a reverse proxy?

Yes, it is absolutely possible to do so. Please consult the [section about configuration regarding proxies](/getting-started/configuration/#proxies).
Yes, it is absolutely possible to do so. Please consult the [section about configuration regarding proxies]({{ site.baseurl }}/getting-started/configuration/#proxies).

### Can I run custom verification/authentication checks before an upload begins?

Yes, this is made possible by the [hook system](/docs/hooks.md) inside the tusd binary. It enables custom routines to be executed when certain events occurs, such as a new upload being created which can be handled by the `pre-create` hook. Inside the corresponding hook file, you can run your own validations against the provided upload metadata to determine whether the action is actually allowed or should be rejected by tusd. Please have a look at the [corresponding documentation](/docs/hooks.md#pre-create) for a more detailed explanation.
Yes, this is made possible by the [hook system]({{ site.baseurl }}/docs/hooks.md) inside the tusd binary. It enables custom routines to be executed when certain events occurs, such as a new upload being created which can be handled by the `pre-create` hook. Inside the corresponding hook file, you can run your own validations against the provided upload metadata to determine whether the action is actually allowed or should be rejected by tusd. Please have a look at the [corresponding documentation]({{ site.baseurl }}/docs/hooks.md#pre-create) for a more detailed explanation.

### I am getting TemporaryErrors (Lockfile created, but doesn't exist)! What can I do?

This error can occur when you are running tusd's disk storage on a file system which does not support hard links. Please consult the [local disk storage documentation](/storage-backends/local-disk/#issues-with-nfs-and-shared-folders) for more details.
This error can occur when you are running tusd's disk storage on a file system which does not support hard links. Please consult the [local disk storage documentation]({{ site.baseurl }}/storage-backends/local-disk/#issues-with-nfs-and-shared-folders) for more details.

### How can I prevent users from downloading the uploaded files?

Tusd allows any user to retrieve a previously uploaded file by issuing a HTTP GET request to the corresponding upload URL. This is possible as long as the uploaded files on the datastore have not been deleted or moved to another location. This can be completely disabled using the [`-disable-download` flag](/getting-started/configuration/#disable-downloads).
Tusd allows any user to retrieve a previously uploaded file by issuing a HTTP GET request to the corresponding upload URL. This is possible as long as the uploaded files on the datastore have not been deleted or moved to another location. This can be completely disabled using the [`-disable-download` flag]({{ site.baseurl }}/getting-started/configuration/#disable-downloads).

### How can I keep the original filename for the uploads?

tusd will generate a unique ID for every upload, e.g. `1881febb4343e9b806cad2e676989c0d`, which is also used as the filename for storing the upload. If you want to keep the original filename, e.g. `my_image.png`, you will have to rename the uploaded file manually after the upload is completed. One can use the [`post-finish` hook](https://github.com/tus/tusd/blob/main/docs/hooks.md#post-finish) to be notified once the upload is completed. The client must also be configured to add the filename to the upload's metadata, which can be [accessed inside the hooks](https://github.com/tus/tusd/blob/main/docs/hooks.md#the-hooks-environment) and used for the renaming operation.

### Does tusd support Cross-Origin Resource Sharing (CORS)?

Yes, tusd does have built-in support for CORS, which can be [fully customized](/getting-started/configuration/#cross-origin-resource-sharing-cors).
Yes, tusd does have built-in support for CORS, which can be [fully customized]({{ site.baseurl }}/getting-started/configuration/#cross-origin-resource-sharing-cors).
Loading

0 comments on commit 8632fda

Please sign in to comment.