@tus/server: allow customising upload url and upload id extraction

[fenos]

Allow full customization of upload url and upload-id extraction from the URL.
Keeping the default behavior intact.

This PR will allow providing an UploadIdGenerator interface with 2 methods to implement:

• generateUrl
• getFileIdFromRequest

This way we can provide users with the possibility of customizing the URL to their liking.
Closes #457

[Murderlon]

Thanks for the contribution. I think it makes sense to offer this feature but I'm not sure about the approach.

• Conceptually, I'd like to keep "models" for simple interfaces/structs, I don't think we need this as a class there. (from that perspective StreamSplitter and Metadata also don't really belong there but that's another conversation).
• This puts a bigger implementation burden on the implementer as the entire generateUrl has to be recreated, including the internal options.
• This makes makes it hard to introduce future changes without breaking custom implementations.

I would go for two simple functions (no class needed I think)

• getFileIdFromRequest as it is currently
• generateUrl ideally gets no internal options, instead it receives host and proto which are done by us internally before passing it in. There should be no need to pass relativeLocation because if that's what you want to do in your custom logic, you can just do that. Same for path, this is already known for yourself top level as you pass it into the server. I wonder if this is possible with composition somehow so that we do have those options in scope but we don't expose it to the implementer.

What do you think?

[fenos]

Thanks for this!

Conceptually, I'd like to keep "models" for simple interfaces/structs, I don't think we need this as a class there. (from that perspective StreamSplitter and Metadata also don't really belong there but that's another conversation).

We can refactor this in another PR

This puts a bigger implementation burden on the implementer as the entire generateUrl has to be recreated, including the internal options.
I would go for two simple functions (no class needed I think)

Not necessarily, because if we go with a class such as the above, we can always extend it and get the default behavior + any additional behavior.

However, I'm not against having them as functions, since they can be equally re-used, but they will need to be exported independently and not embedded in the BaseHandler if we want to allow to be re-used

generateUrl ideally gets no internal options, instead it receives host and proto which are done by us internally before passing it in. There should be no need to pass relativeLocation because if that's what you want to do in your custom logic, you can just do that. Same for path, this is already known for yourself top level as you pass it into the server. I wonder if this is possible with composition somehow so that we do have those options in scope but we don't expose it to the implementer.

Ok, this looks like a good compromise!

[fenos]

@Murderlon i've reworked the implementation and now the interface looks as following:

new Server({
  ...
  generateUrl: (req, { proto, host, baseUrl, path, id}) => {
     return 'whatever url composition you want'
  },
  getFileIdFromRequest: (req) => {
     return myCustomExtraction()
  }
})

we can also call the default functions in case we want to just add encoding for example:

import {generateUrl, getFileIdFromRequest} from '@tus/server'

new Server({
  ...
  generateUrl: (req, { proto, host, baseUrl, path, id}) => {
     id = Buffer.from(id, 'utf-8').toString('base64url')
     return generateUrl(id, { proto, host, baseUrl, path })
  },
  getFileIdFromRequest: (req) => {
    const id = getFileIdFromRequest(req.url as string)
    if (!id) return false
    return Buffer.from(id, 'base64url').toString('utf-8')
  }
})

[Murderlon]

Thanks for applying the feedback! I think we're close to being ready. Some final things:

• We need docs for this
• Would be nice to have a simple test in BaseHandler.test.ts
• I'm inclined not to export the default functions for this. Doesn't add that much value on top of already handling proto and host and we increase the API surface and loose flexibility to change the internal signature.
• If we don't export, we can move the extractHostAndProto into BaseHandler and inline the generateUrl logic at line 56. Similarly, getFileIdFromRequest can just be inline logic at line 69.

What do you think?

[fenos]

• We need docs for this ✅
• Would be nice to have a simple test in BaseHandler.test.ts ✅
• I'm inclined not to export the default functions for this. Doesn't add that much value on top of already handling proto and host and we increase the API surface and loose flexibility to change the internal signature.
  If we don't export, we can move the extractHostAndProto into BaseHandler and inline the generateUrl logic at line 56. Similarly, getFileIdFromRequest can just be inline logic at line 69. ✅

All ready!

[Murderlon]

Perfect! ✨

[fenos]

@Murderlon ready to merge 🎉