Package: taskcluster-urls
Taskcluster URL Building LibraryA simple library to generate URLs for various Taskcluster resources across our various deployment methods.This serves as both a simple shim for projects that use JavaScript but also is the reference implementation for
how we define these paths.URLs are defined in the 'Taskcluster URL Format.ChangelogView the changelog on thereleases page.RequirementsThis is tested on and should run on any of Node.js{8, 10}.General UsageWhile the capitalization and punctunation of the function names varies depending on the language, each language provides the following methods:methodresultapi(rootUrl, service, version, path) -><rootUrl>/api/<service>/<version>/<path>apiReference(rootUrl, service, version) -><rootUrl>/references/<service>/<version>/api.jsondocs(rootUrl, path) -><rootUrl>/docs/<path>exchangeReference(rootUrl, service, version) -><rootUrl>/references/<service>/<version>/exchanges.jsonschema(rootUrl, service, schema) -><rootUrl>/schemas/<service>/<schema>apiSchema(rootUrl, version) -><rootUrl>/schemas/common/api-reference-<version>.jsonexchangesSchema(rootUrl, version) -><rootUrl>/schemas/common/exchanges-reference-<version>.jsonapiManifestSchema(rootUrl, version) -><rootUrl>/schemas/common/manifest-<version>.jsonmetadataMchema(rootUrl) -><rootUrl>/schemas/common/metadata-metaschema.jsonui(rootUrl, path) -><rootUrl>/<path>apiManifest(rootUrl) -><rootUrl>/references/manifest.jsonnormalizeRootUrl(rootUrl) ->the normal form of the given rootUrltestRootUrl() ->https://tc-tests.example.comtestRootUrl()is used to share a common fakerootUrlbetween various Taskcluster mocks in testing.
The URL does not resolve.JS UsageThis package exports several methods for generating URLs conditionally based on
a root URL, as well as a few helper classes for generating URLs for a pre-determined
root URL:api(rootUrl, service, version, path)->StringapiReference(rootUrl, service, version)->Stringdocs(rootUrl, path)->StringexchangeReference(rootUrl, service, version)->Stringschema(rootUrl, service, schema)->StringapiManifestSchema(rootUrl, version)->StringapiReferenceSchema(rootUrl, version)->StringexchangesReferenceSchema(rootUrl, version)->StringmetadataMetaschema(rootUrl)->Stringui(rootUrl, path)->StringapiManifest(rootUrl)->StringtestRootUrl()->StringwithRootUrl(rootUrl)->Classinstance for above methodsnormalizeRootUrl(rootUrl)->String(the "normalized" form of the given rootUrl)// Specifying root URL every time:constlibUrls=require('taskcluster-lib-urls');libUrls.api(rootUrl,'auth','v1','foo/bar');libUrls.schema(rootUrl,'auth','v1/foo.yml');// Note that schema names have versions in themlibUrls.apiReference(rootUrl,'auth','v1');libUrls.exchangeReference(rootUrl,'auth','v1');libUrls.ui(rootUrl,'foo/bar');libUrls.apiManifest(rootUrl);libUrls.docs(rootUrl,'foo/bar');// Specifying root URL in advance:constlibUrls=require('taskcluster-lib-urls');consturls=libUrls.withRoot(rootUrl);urls.api('auth','v1','foo/bar');urls.schema('auth','v1/foo.yml');urls.apiReference('auth','v1');urls.exchangeReference('auth','v1');urls.ui('foo/bar');urls.apiManifest();urls.docs('foo/bar');If you would like, you can set this up viataskcluster-lib-loaderas follows:{libUrlss:{require:['cfg'],setup:({cfg})=>withRootUrl(cfg.rootURl),},}Test with:yarn install
yarn testGo UsageThe go package exports the following functions:funcAPI(rootURLstring,servicestring,versionstring,pathstring)stringfuncAPIReference(rootURLstring,servicestring,versionstring)stringfuncDocs(rootURLstring,pathstring)stringfuncExchangeReference(rootURLstring,servicestring,versionstring)stringfuncSchema(rootURLstring,servicestring,namestring)stringfuncAPIManifestSchema(rootURLstring,versionstring)stringfuncAPIReferenceSchema(rootURLstring,versionstring)stringfuncExchangesReferenceSchema(rootURLstring,versionstring)stringfuncMetadataMetaschema(rootURLstring)stringfuncUI(rootURLstring,pathstring)stringfuncAPIManifest(rootURLstring)stringfuncNormalizeRootURL(rootURLstring)stringInstall with:go install ./..Test with:go test -v ./...Python UsageYou can install the python client withpip install taskcluster-urls;importtaskcluster_urlstaskcluster_urls.api(root_url,'auth','v1','foo/bar')taskcluster_urls.schema(root_url,'auth','v1/foo.yml')# Note that schema names have versions in themtaskcluster_urls.api_manifest_schema(root_url,'v1')taskcluster_urls.api_reference_schema(root_url,'v1')taskcluster_urls.exchanges_reference_schema(root_url,'v1')taskcluster_urls.metadata_metaschema(root_url,'v1')taskcluster_urls.api_reference(root_url,'auth','v1')taskcluster_urls.exchange_reference(root_url,'auth','v1')taskcluster_urls.ui(root_url,'foo/bar')taskcluster_urls.apiManifest(root_url)taskcluster_urls.docs(root_url,'foo/bar')taskcluster_urls.normalize_root_url(root_url)taskcluster_urls.test_root_url()Test with:toxJava UsageIn order to use this library from your maven project, simply include it as a project dependency:<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>org.mozilla.taskcluster</groupId>
      <artifactId>taskcluster-lib-urls</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>
</project>The taskcluster-lib-urls artifacts are now available from themaven central repository:Search ResultsDirectory ListingTo use the library, do as follows:importorg.mozilla.taskcluster.urls.*;...URLProviderurlProvider=URLs.provider("https://mytaskcluster.acme.org");StringfooBarAPI=urlProvider.api("auth","v1","foo/bar");StringfooSchema=urlProvider.schema("auth","v1/foo.yml");// Note that schema names have versions in themStringapiSchema=urlProvider.apiReferenceSchema("v1");StringexchangesSchema=urlProvider.exchangesReferenceSchema("v1");StringmanifestSchema=urlProvider.apiManifestSchema("v1");Stringmetaschema=urlProvider.metadataMetaschema();StringauthAPIRef=urlProvider.apiReference("auth","v1");StringauthExchangesRef=urlProvider.exchangeReference("auth","v1");StringuiFooBar=urlProvider.ui("foo/bar");StringapiManifest=urlProvider.apiManifest();StringdocsFooBar=urlProvider.docs("foo/bar");...Install with:mvn installTest with:mvn testReleasingNew releases should be tested on Travis and Taskcluster to allow for all supported versions of various languages to be tested. Once satisfied that it works, new versions should be created withnpm versionrather than by manually editingpackage.jsonand tags should be pushed to Github.Make the Node release first, as Python's version depends on itspackage.json.  This follows the typical tag-and-push-to-publish approach:$npmversionminor# or patch, or major$gitpushupstreamOnce that's done, build the Python sdists (only possible by themaintainers on pypi):rm-rfdist/*
pythonsetup.pysdistbdist_wheel
python3setup.pybdist_wheel
pipinstalltwine
twineuploaddist/*Make sure to updatethe changelog!LicenseMozilla Public License Version 2.0