@angular-wave/angular.ts 0.9.3 → 0.9.4

package/src/services/http-backend/http-backend.spec.js

@@ -1,389 +0,0 @@
-import { Angular } from "../../angular.js";
-import { createHttpBackend } from "./http-backend.js";
-import sinon from "sinon";
-
-describe("$httpBackend", () => {
-  let $backend;
-  let xhr;
-  let callback;
-  let requests;
-  let angular;
-
-  beforeEach(() => {
-    xhr = sinon.useFakeXMLHttpRequest();
-    requests = [];
-    xhr.onCreate = function (req) {
-      requests.push(req);
-    };
-    angular = window.angular = new Angular();
-    $backend = createHttpBackend();
-    callback = jasmine.createSpy("done");
-  });
-
-  afterEach(() => {
-    xhr.restore();
-  });
-
-  it("should do basics - open async xhr and send data", () => {
-    $backend("GET", "/some-url", "some-data", () => {});
-    expect(requests.length).toBe(1);
-    expect(requests[0].method).toBe("GET");
-    expect(requests[0].url).toBe("/some-url");
-    expect(requests[0].requestBody).toBe("some-data");
-    expect(requests[0].async).toBe(true);
-  });
-
-  it("should pass null to send if no body is set", () => {
-    $backend("GET", "/some-url", undefined, () => {});
-    expect(requests[0].requestBody).toBe(null);
-  });
-
-  it("should pass the correct falsy value to send if falsy body is set (excluding undefined, NaN)", () => {
-    [false, 0, "", null].forEach((value, index) => {
-      $backend("GET", "/some-url", value, () => {});
-      expect(requests[index].requestBody).toBe(value);
-    });
-  });
-
-  it("should pass NaN to send if NaN body is set", () => {
-    $backend("GET", "/some-url", NaN, () => {});
-    expect(isNaN(requests[0].requestBody)).toEqual(true);
-  });
-
-  it("should call completion function with xhr.statusText if present", () => {
-    callback.and.callFake((status, response, headers, statusText) => {
-      expect(statusText).toBe("OK");
-    });
-
-    $backend("GET", "/some-url", null, callback);
-    requests[0].respond(200);
-    expect(callback).toHaveBeenCalled();
-  });
-
-  it("should set only the requested headers", () => {
-    $backend("POST", "URL", null, () => {}, {
-      "X-header1": "value1",
-      "X-header2": "value2",
-    });
-    expect(requests[0].requestHeaders["X-header1"]).toEqual("value1");
-    expect(requests[0].requestHeaders["X-header2"]).toEqual("value2");
-  });
-
-  it("should not try to read response data when request is aborted", () => {
-    callback.and.callFake((status, response, headers, statusText) => {
-      expect(status).toBe(-1);
-      expect(response).toBe(null);
-      expect(headers).toBe(null);
-      expect(statusText).toBe("");
-    });
-    $backend("GET", "/url", null, callback, {}, 2000);
-    requests[0].respond(0);
-    expect(callback).toHaveBeenCalled();
-  });
-
-  it("should complete the request on abort", () => {
-    callback.and.callFake(
-      (status, response, headers, statusText, xhrStatus) => {
-        expect(status).toBe(-1);
-        expect(response).toBe(null);
-        expect(headers).toBe(null);
-        expect(statusText).toBe("");
-      },
-    );
-    $backend("GET", "/url", null, callback, {});
-
-    expect(callback).not.toHaveBeenCalled();
-    requests[0].error();
-    expect(callback).toHaveBeenCalled();
-  });
-
-  it("should complete the request on error", () => {
-    callback.and.callFake(
-      (status, response, headers, statusText, xhrStatus) => {
-        expect(status).toBe(-1);
-        expect(response).toBe(null);
-        expect(headers).toBe(null);
-        expect(statusText).toBe("");
-        expect(xhrStatus).toBe("error");
-      },
-    );
-    $backend("GET", "/url", null, callback, {});
-
-    expect(callback).not.toHaveBeenCalled();
-    requests[0].error();
-    expect(callback).toHaveBeenCalled();
-  });
-
-  it("should complete the request on success", () => {
-    callback.and.callFake(
-      (status, response, headers, statusText, xhrStatus) => {
-        expect(status).toBe(200);
-        expect(response).toBe("response");
-        expect(headers).toBe("");
-        expect(statusText).toBe("OK");
-        expect(xhrStatus).toBe("complete");
-      },
-    );
-    $backend("GET", "/url", null, callback, {});
-
-    expect(callback).not.toHaveBeenCalled();
-    requests[0].respond(200, "", "response");
-    expect(callback).toHaveBeenCalled();
-  });
-
-  // it("should set withCredentials", () => {
-  //   $backend("GET", "/some.url", null, callback, {}, null, true);
-  //   expect(requests[0].withCredentials).toBeTrue();
-  // });
-
-  // it("should abort request on $timeout promise resolution", () => {
-  //   callback.and.callFake(
-  //     (status, response, headers, statusText, xhrStatus) => {
-  //       expect(status).toBe(-1);
-  //       expect(xhrStatus).toBe("timeout");
-  //     },
-  //   );
-
-  //   $backend(
-  //     "GET",
-  //     "/url",
-  //     null,
-  //     callback,
-  //     {},
-  //     setTimeout(() => {}, 2000),
-  //   );
-  //   spyOn(xhr, "abort");
-  //   expect(xhr.abort).toHaveBeenCalled();
-
-  //   requests[0].abort();
-  //   expect(callback).toHaveBeenCalled();
-  // });
-
-  // it("should not abort resolved request on timeout promise resolution", () => {
-  //   callback.and.callFake((status, response) => {
-  //     expect(status).toBe(200);
-  //   });
-
-  //   $backend(
-  //     "GET",
-  //     "/url",
-  //     null,
-  //     callback,
-  //     {},
-  //     setTimeout(() => {}, 2000),
-  //   );
-  //   xhr = MockXhr.$$lastInstance;
-  //   spyOn(xhr, "abort");
-
-  //   xhr.status = 200;
-  //   xhr.onload();
-  //   expect(callback).toHaveBeenCalled();
-
-  //   $timeout.flush();
-  //   expect(xhr.abort).not.toHaveBeenCalled();
-  // });
-
-  // it("should abort request on canceler promise resolution", () => {
-  //   const canceler = Promise.withResolvers();
-
-  //   callback.and.callFake(
-  //     (status, response, headers, statusText, xhrStatus) => {
-  //       expect(status).toBe(-1);
-  //       expect(xhrStatus).toBe("abort");
-  //     },
-  //   );
-
-  //   $backend("GET", "/url", null, callback, {}, canceler.promise);
-  //   xhr = MockXhr.$$lastInstance;
-
-  //   canceler.resolve();
-  //   $browser.defer.flush();
-
-  //   expect(callback).toHaveBeenCalled();
-  // });
-
-  // it("should cancel timeout on completion", () => {
-  //   callback.and.callFake((status, response) => {
-  //     expect(status).toBe(200);
-  //   });
-
-  //   $backend("GET", "/url", null, callback, {}, 2000);
-  //   xhr = MockXhr.$$lastInstance;
-  //   spyOn(xhr, "abort");
-
-  //   expect($browser.deferredFns[0].time).toBe(2000);
-
-  //   xhr.status = 200;
-  //   xhr.onload();
-  //   expect(callback).toHaveBeenCalled();
-
-  //   expect($browser.deferredFns.length).toBe(0);
-  //   expect(xhr.abort).not.toHaveBeenCalled();
-  // });
-
-  // it('should call callback with xhrStatus "abort" on explicit xhr.abort() when $timeout is set', () => {
-  //   callback.and.callFake(
-  //     (status, response, headers, statusText, xhrStatus) => {
-  //       expect(status).toBe(-1);
-  //       expect(xhrStatus).toBe("abort");
-  //     },
-  //   );
-
-  //   $backend(
-  //     "GET",
-  //     "/url",
-  //     null,
-  //     callback,
-  //     {},
-  //     setTimeout(() => {}, 2000),
-  //   );
-  //   spyOn(xhr, "abort").and.callThrough();
-
-  //   xhr.abort();
-
-  //   expect(callback).toHaveBeenCalled();
-  // });
-
-  it("should set up event listeners", () => {
-    const progressFn = function () {
-      "progressFn";
-    };
-    $backend("GET", "/url", null, callback, {}, null, null, null, {
-      progress: progressFn,
-    });
-    expect(requests[0].eventListeners.progress[1].listener).toBe(progressFn);
-    //expect(requests[0].eventListeners.progress[1].listener).toBe(uploadProgressFn);
-  });
-
-  // describe("responseType", () => {
-  //   it("should set responseType and return xhr.response", () => {
-  //     $backend("GET", "/whatever", null, callback, {}, null, null, "blob");
-
-  //     const xhrInstance = MockXhr.$$lastInstance;
-  //     expect(xhrInstance.responseType).toBe("blob");
-
-  //     callback.and.callFake((status, response) => {
-  //       expect(response).toBe(xhrInstance.response);
-  //     });
-
-  //     xhrInstance.response = { some: "object" };
-  //     xhrInstance.onload();
-
-  //     expect(callback).toHaveBeenCalled();
-  //   });
-
-  //   it("should read responseText if response was not defined", () => {
-  //     //  old browsers like IE9, don't support responseType, so they always respond with responseText
-
-  //     $backend("GET", "/whatever", null, callback, {}, null, null, "blob");
-
-  //     const xhrInstance = MockXhr.$$lastInstance;
-  //     const responseText = '{"some": "object"}';
-  //     expect(xhrInstance.responseType).toBe("blob");
-
-  //     callback.and.callFake((status, response) => {
-  //       expect(response).toBe(responseText);
-  //     });
-
-  //     xhrInstance.responseText = responseText;
-  //     xhrInstance.onload();
-
-  //     expect(callback).toHaveBeenCalled();
-  //   });
-  // });
-
-  // describe("protocols that return 0 status code", () => {
-  //   function respond(status, content) {
-  //     xhr = MockXhr.$$lastInstance;
-  //     xhr.status = status;
-  //     xhr.responseText = content;
-  //     xhr.onload();
-  //   }
-
-  //   beforeEach(() => {
-  //     $backend = createHttpBackend($browser, createMockXhr);
-  //   });
-
-  //   it("should convert 0 to 200 if content and file protocol", () => {
-  //     $backend("GET", "file:///whatever/index.html", null, callback);
-  //     respond(0, "SOME CONTENT");
-
-  //     expect(callback).toHaveBeenCalled();
-  //     expect(callback.calls.mostRecent().args[0]).toBe(200);
-  //   });
-
-  //   it("should convert 0 to 200 if content for protocols other than file", () => {
-  //     $backend("GET", "someProtocol:///whatever/index.html", null, callback);
-  //     respond(0, "SOME CONTENT");
-
-  //     expect(callback).toHaveBeenCalled();
-  //     expect(callback.calls.mostRecent().args[0]).toBe(200);
-  //   });
-
-  //   it("should convert 0 to 404 if no content and file protocol", () => {
-  //     $backend("GET", "file:///whatever/index.html", null, callback);
-  //     respond(0, "");
-
-  //     expect(callback).toHaveBeenCalled();
-  //     expect(callback.calls.mostRecent().args[0]).toBe(404);
-  //   });
-
-  //   it("should not convert 0 to 404 if no content for protocols other than file", () => {
-  //     $backend("GET", "someProtocol:///whatever/index.html", null, callback);
-  //     respond(0, "");
-
-  //     expect(callback).toHaveBeenCalled();
-  //     expect(callback.calls.mostRecent().args[0]).toBe(0);
-  //   });
-
-  // it("should convert 0 to 404 if no content - relative url", () => {
-  //   const originalUrlParsingNode = urlParsingNode;
-
-  //   // temporarily overriding the DOM element to pretend that the test runs origin with file:// protocol
-  //   urlParsingNode = {
-  //     hash: "#/C:/",
-  //     host: "",
-  //     hostname: "",
-  //     href: "file:///C:/base#!/C:/foo",
-  //     pathname: "/C:/foo",
-  //     port: "",
-  //     protocol: "file:",
-  //     search: "",
-  //     setAttribute: () => {},
-  //   };
-
-  //   try {
-  //     $backend("GET", "/whatever/index.html", null, callback);
-  //     respond(0, "");
-
-  //     expect(callback).toHaveBeenCalled();
-  //     expect(callback.calls.mostRecent().args[0]).toBe(404);
-  //   } finally {
-  //     urlParsingNode = originalUrlParsingNode;
-  //   }
-  // });
-
-  // it("should return original backend status code if different from 0", () => {
-  //   // request to http://
-  //   $backend("POST", "http://rest_api/create_whatever", null, callback);
-  //   respond(201, "");
-
-  //   expect(callback).toHaveBeenCalled();
-  //   expect(callback.calls.mostRecent().args[0]).toBe(201);
-
-  //   // request to file://
-  //   $backend("POST", "file://rest_api/create_whatever", null, callback);
-  //   respond(201, "");
-
-  //   expect(callback).toHaveBeenCalled();
-  //   expect(callback.calls.mostRecent().args[0]).toBe(201);
-
-  //   // request to file:// with HTTP status >= 300
-  //   $backend("POST", "file://rest_api/create_whatever", null, callback);
-  //   respond(503, "");
-
-  //   expect(callback).toHaveBeenCalled();
-  //   expect(callback.calls.mostRecent().args[0]).toBe(503);
-  // });
-  // });
-});

package/src/services/sce/sce.md

@@ -1,300 +0,0 @@
-/\*\*
-
-- The $sceProvider provider allows developers to configure the {@link ng.$sce $sce} service.
-- - enable/disable Strict Contextual Escaping (SCE) in a module
-- - override the default implementation with a custom delegate
--
-- Read more about {@link ng.$sce Strict Contextual Escaping (SCE)}.
-  \*/
-
-/\*\*
-
--
-- `$sce` is a service that provides Strict Contextual Escaping services to AngularTS.
--
-- ## Strict Contextual Escaping
--
-- Strict Contextual Escaping (SCE) is a mode in which AngularTS constrains bindings to only render
-- trusted values. Its goal is to assist in writing code in a way that (a) is secure by default, and
-- (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a lot easier.
--
-- ### Overview
--
-- To systematically block XSS security bugs, AngularTS treats all values as untrusted by default in
-- HTML or sensitive URL bindings. When binding untrusted values, AngularTS will automatically
-- run security checks on them (sanitizations, trusted URL resource, depending on context), or throw
-- when it cannot guarantee the security of the result. That behavior depends strongly on contexts:
-- HTML can be sanitized, but template URLs cannot, for instance.
--
-- To illustrate this, consider the `ng-bind-html` directive. It renders its value directly as HTML:
-- we call that the _context_. When given an untrusted input, AngularTS will attempt to sanitize it
-- before rendering if a sanitizer is available, and throw otherwise. To bypass sanitization and
-- render the input as-is, you will need to mark it as trusted for that context before attempting
-- to bind it.
--
-- As of version 1.2, AngularTS ships with SCE enabled by default.
--
-- ### In practice
--
-- Here's an example of a binding in a privileged context:
--
-- ```
-
-  ```
-
-- <input ng-model="userHtml" aria-label="User input">
-- <div ng-bind-html="userHtml"></div>
-- ```
-
-  ```
-
--
-- Notice that `ng-bind-html` is bound to `userHtml` controlled by the user. With SCE
-- disabled, this application allows the user to render arbitrary HTML into the DIV, which would
-- be an XSS security bug. In a more realistic example, one may be rendering user comments, blog
-- articles, etc. via bindings. (HTML is just one example of a context where rendering user
-- controlled input creates security vulnerabilities.)
--
-- For the case of HTML, you might use a library, either on the client side, or on the server side,
-- to sanitize unsafe HTML before binding to the value and rendering it in the document.
--
-- How would you ensure that every place that used these types of bindings was bound to a value that
-- was sanitized by your library (or returned as safe for rendering by your server?) How can you
-- ensure that you didn't accidentally delete the line that sanitized the value, or renamed some
-- properties/fields and forgot to update the binding to the sanitized value?
--
-- To be secure by default, AngularTS makes sure bindings go through that sanitization, or
-- any similar validation process, unless there's a good reason to trust the given value in this
-- context. That trust is formalized with a function call. This means that as a developer, you
-- can assume all untrusted bindings are safe. Then, to audit your code for binding security issues,
-- you just need to ensure the values you mark as trusted indeed are safe - because they were
-- received from your server, sanitized by your library, etc. You can organize your codebase to
-- help with this - perhaps allowing only the files in a specific directory to do this.
-- Ensuring that the internal API exposed by that code doesn't markup arbitrary values as safe then
-- becomes a more manageable task.
--
-- In the case of AngularTS' SCE service, one uses {@link ng.$sce#trustAs $sce.trustAs}
-- (and shorthand methods such as {@link ng.$sce#trustAsHtml $sce.trustAsHtml}, etc.) to
-- build the trusted versions of your values.
--
-- ### How does it work?
--
-- In privileged contexts, directives and code will bind to the result of {@link ng.$sce#getTrusted
-- $sce.getTrusted(context, value)} rather than to the value directly. Think of this function as
-- a way to enforce the required security context in your data sink. Directives use {@link
-- ng.$sceparseAs $sce.parseAs} rather than `$parse` to watch attribute bindings, which performs
-- the {@link ng.$sce#getTrusted $sce.getTrusted} behind the scenes on non-constant literals. Also,
-- when binding without directives, AngularTS will understand the context of your bindings
-- automatically.
--
-- As an example, {@link ng.directive:ngBindHtml ngBindHtml} uses {@link
-- ng.$sceparseAsHtml $sce.parseAsHtml(binding expression)}. Here's the actual code (slightly
-- simplified):
--
-- ```
-
-  ```
-
-- let ngBindHtmlDirective = ['$sce', function($sce) {
-- return function(scope, element, attr) {
--     scope.$watch($sce.parseAsHtml(attr.ngBindHtml), function(value) {
--       element.html(value || '');
--     });
-- };
-- }];
-- ```
-
-  ```
-
--
-- ### Impact on loading templates
--
-- This applies both to the {@link ng.directive:ngInclude `ng-include`} directive as well as
-- `templateUrl`'s specified by {@link guide/directive directives}.
--
-- By default, AngularTS only loads templates from the same domain and protocol as the application
-- document. This is done by calling {@link ng.$sce#getTrustedResourceUrl
-- $sce.getTrustedResourceUrl} on the template URL. To load templates from other domains and/or
-- protocols, you may either add them to the {@link ng.$sceDelegateProvider#trustedResourceUrlList
-- trustedResourceUrlList} or {@link ng.$sce#trustAsResourceUrl wrap them} into trusted values.
--
-- _Please note_:
-- The browser's
-- [Same Origin Policy](https://code.google.com/p/browsersec/wiki/Part2#Same-origin_policy_for_XMLHttpRequest)
-- and [Cross-Origin Resource Sharing (CORS)](http://www.w3.org/TR/cors/)
-- policy apply in addition to this and may further restrict whether the template is successfully
-- loaded. This means that without the right CORS policy, loading templates from a different domain
-- won't work on all browsers. Also, loading templates from `file://` URL does not work on some
-- browsers.
--
-- ### This feels like too much overhead
--
-- It's important to remember that SCE only applies to interpolation expressions.
--
-- If your expressions are constant literals, they're automatically trusted and you don't need to
-- call `$sce.trustAs` on them (e.g.
-- `<div ng-bind-html="'<b>implicitly trusted</b>'"></div>`) just works (remember to include the
-- `ngSanitize` module). The `$sceDelegate` will also use the `$sanitize` service if it is available
-- when binding untrusted values to `$sce.HTML` context.
-- AngularTS provides an implementation in `angular-sanitize.js`, and if you
-- wish to use it, you will also need to depend on the {@link ngSanitize `ngSanitize`} module in
-- your application.
--
-- The included {@link ng.$sceDelegate $sceDelegate} comes with sane defaults to allow you to load
-- templates in `ng-include` from your application's domain without having to even know about SCE.
-- It blocks loading templates from other domains or loading templates over http from an https
-- served document. You can change these by setting your own custom {@link
-- ng.$sceDelegateProvider#trustedResourceUrlList trusted resource URL list} and {@link
-- ng.$sceDelegateProvider#bannedResourceUrlList banned resource URL list} for matching such URLs.
--
-- This significantly reduces the overhead. It is far easier to pay the small overhead and have an
-- application that's secure and can be audited to verify that with much more ease than bolting
-- security onto an application later.
--
-- <a name="contexts"></a>
-- ### What trusted context types are supported?
--
-- | Context | Notes |
-- |---------------------|----------------|
-- | `$sce.HTML` | For HTML that's safe to source into the application. The {@link ng.directive:ngBindHtml ngBindHtml} directive uses this context for bindings. If an unsafe value is encountered and the {@link ngSanitize $sanitize} module is present this will sanitize the value instead of throwing an error. |
-- | `$sce.CSS` | For CSS that's safe to source into the application. Currently unused. Feel free to use it in your own directives. |
-- | `$sce.MEDIA_URL` | For URLs that are safe to render as media. Is automatically converted from string by sanitizing when needed. |
-- | `$sce.URL` | For URLs that are safe to follow as links. Is automatically converted from string by sanitizing when needed. Note that `$sce.URL` makes a stronger statement about the URL than `$sce.MEDIA_URL` does and therefore contexts requiring values trusted for `$sce.URL` can be used anywhere that values trusted for `$sce.MEDIA_URL` are required.|
-- | `$sce.RESOURCE_URL` | For URLs that are not only safe to follow as links, but whose contents are also safe to include in your application. Examples include `ng-include`, `src` / `ngSrc` bindings for tags other than `IMG` (e.g. `IFRAME`, `OBJECT`, etc.) <br><br>Note that `$sce.RESOURCE_URL` makes a stronger statement about the URL than `$sce.URL` or `$sce.MEDIA_URL` do and therefore contexts requiring values trusted for `$sce.RESOURCE_URL` can be used anywhere that values trusted for `$sce.URL` or `$sce.MEDIA_URL` are required. <br><br> The {@link $sceDelegateProvider#trustedResourceUrlList $sceDelegateProvider#trustedResourceUrlList()} and {@link $sceDelegateProvider#bannedResourceUrlList $sceDelegateProvider#bannedResourceUrlList()} can be used to restrict trusted origins for `RESOURCE_URL` |
-- | `$sce.JS` | For JavaScript that is safe to execute in your application's context. Currently unused. Feel free to use it in your own directives. |
--
--
-- <div class="alert alert-warning">
-- Be aware that, before AngularTS 1.7.0, `a[href]` and `img[src]` used to sanitize their
-- interpolated values directly rather than rely upon {@link ng.$sce#getTrusted `$sce.getTrusted`}.
--
-- **As of 1.7.0, this is no longer the case.**
--
-- Now such interpolations are marked as requiring `$sce.URL` (for `a[href]`) or `$sce.MEDIA_URL`
-- (for `img[src]`), so that the sanitization happens (via `$sce.getTrusted...`) when the `$interpolate`
-- service evaluates the expressions.
-- </div>
--
-- There are no CSS or JS context bindings in AngularTS currently, so their corresponding `$sce.trustAs`
-- functions aren't useful yet. This might evolve.
--
-- ### Format of items in {@link ng.$sceDelegateProvider#trustedResourceUrlList trustedResourceUrlList}/{@link ng.$sceDelegateProvider#bannedResourceUrlList bannedResourceUrlList} <a name="resourceUrlPatternItem"></a>
--
-- Each element in these arrays must be one of the following:
--
-- - **'self'**
-- - The special **string**, `'self'`, can be used to match against all URLs of the \*\*same
--      domain** as the application document using the **same protocol**.
-- - **String** (except the special value `'self'`)
-- - The string is matched against the full _normalized / absolute URL_ of the resource
--      being tested (substring matches are not good enough.)
-- - There are exactly **two wildcard sequences** - `*` and `**`. All other characters
--      match themselves.
-- - `*`: matches zero or more occurrences of any character other than one of the following 6
--      characters: '`:`', '`/`', '`.`', '`?`', '`&`' and '`;`'.  It's a useful wildcard for use
--      for matching resource URL lists.
-- - `**`: matches zero or more occurrences of _any_ character. As such, it's not
--      appropriate for use in a scheme, domain, etc. as it would match too much.  (e.g.
--      http://**.example.com/ would match http://evil.com/?ignore=.example.com/ and that might
--      not have been the intention.)  Its usage at the very end of the path is ok.  (e.g.
--      http://foo.example.com/templates/**).
-- - **RegExp** (_see caveat below_)
-- - _Caveat_: While regular expressions are powerful and offer great flexibility, their syntax
--      (and all the inevitable escaping) makes them *harder to maintain*.  It's easy to
--      accidentally introduce a bug when one updates a complex expression (imho, all regexes should
--      have good test coverage).  For instance, the use of `.` in the regex is correct only in a
--      small number of cases.  A `.` character in the regex used when matching the scheme or a
--      subdomain could be matched against a `:` or literal `.` that was likely not intended.   It
--      is highly recommended to use the string patterns and only fall back to regular expressions
--      as a last resort.
-- - The regular expression must be an instance of RegExp (i.e. not a string.) It is
--      matched against the **entire** *normalized / absolute URL* of the resource being tested
--      (even when the RegExp did not have the `^` and `$` codes.)  In addition, any flags
--      present on the RegExp (such as multiline, global, ignoreCase) are ignored.
-- - If you are generating your JavaScript from some other templating engine (not
--      recommended, e.g. in issue [#4006](https://github.com/angular/angular.js/issues/4006)),
--      remember to escape your regular expression (and be aware that you might need more than
--      one level of escaping depending on your templating engine and the way you interpolated
--      the value.)  Do make use of your platform's escaping mechanism as it might be good
--      enough before coding your own.  E.g. Ruby has
--      [Regexp.escape(str)](http://www.ruby-doc.org/core-2.0.0/Regexp.html#method-c-escape)
--      and Python has [re.escape](http://docs.python.org/library/re.html#re.escape).
--      Javascript lacks a similar built in function for escaping.  Take a look at Google
--      Closure library's [goog.string.regExpEscape(s)](
--      http://docs.closure-library.googlecode.com/git/closure_goog_string_string.js.source.html#line962).
--
-- Refer {@link ng.$sceDelegateProvider $sceDelegateProvider} for an example.
--
--
-- ## Can I disable SCE completely?
--
-- Yes, you can. However, this is strongly discouraged. SCE gives you a lot of security beneits
-- for little coding overhead. It will be much harder to take an SCE disabled application and
-- either secure it on your own or enable SCE at a later stage. It might make sense to disable SCE
-- for cases where you have a lot of existing code that was written before SCE was introduced and
-- you're migrating them a module at a time. Also do note that this is an app-wide setting, so if
-- you are writing a library, you will cause security bugs applications using it.
--
-- That said, here's how you can completely disable SCE:
--
-- ```
-
-  ```
-
-- angular.module('myAppWithSceDisabledmyApp', []).config(function($sceProvider) {
-- // Completely disable SCE. For demonstration purposes only!
-- // Do not use in new projects or libraries.
-- $sceProvider.enabled(false);
-- });
-- ```
-
-  ```
-
-- \*/
-
-/\* Design notes on the default implementation for SCE.
-
--
-- The API contract for the SCE delegate
-- ***
-- The SCE delegate object must provide the following 3 methods:
--
-- - trustAs(contextEnum, value)
--     This method is used to tell the SCE service that the provided value is OK to use in the
--     contexts specified by contextEnum.  It must return an object that will be accepted by
--     getTrusted() for a compatible contextEnum and return this value.
--
-- - valueOf(value)
--     For values that were not produced by trustAs(), return them as is.  For values that were
--     produced by trustAs(), return the corresponding input value to trustAs.  Basically, if
--     trustAs is wrapping the given values into some type, this operation unwraps it when given
--     such a value.
--
-- - getTrusted(contextEnum, value)
--     This function should return the value that is safe to use in the context specified by
--     contextEnum or throw and exception otherwise.
--
-- NOTE: This contract deliberately does NOT state that values returned by trustAs() must be
-- opaque or wrapped in some holder object. That happens to be an implementation detail. For
-- instance, an implementation could maintain a registry of all trusted objects by context. In
-- such a case, trustAs() would return the same object that was passed in. getTrusted() would
-- return the same object passed in if it was found in the registry under a compatible context or
-- throw an exception otherwise. An implementation might only wrap values some of the time based
-- on some criteria. getTrusted() might return a value and not throw an exception for special
-- constants or objects even if not wrapped. All such implementations fulfill this contract.
--
--
-- A note on the inheritance model for SCE contexts
-- ***
-- I've used inheritance and made RESOURCE_URL wrapped types a subtype of URL wrapped types. This
-- is purely an implementation details.
--
-- The contract is simply this:
--
--     getTrusted($sce.RESOURCE_URL, value) succeeding implies that getTrusted($sce.URL, value)
--     will also succeed.
--
-- Inheritance happens to capture this in a natural way. In some future, we may not use
-- inheritance anymore. That is OK because no code outside of sce.js and sceSpecs.js would need to
-- be aware of this detail.
-  \*/